Table of Contents

Class ShareServiceClient

Namespace
Azure.Storage.Files.Shares
Assembly
Azure.Storage.Files.Shares.dll

The ShareServiceClient allows you to manipulate Azure Storage service resources and shares. The storage account provides the top-level namespace for the File service.

public class ShareServiceClient
Inheritance
ShareServiceClient
Inherited Members

Constructors

ShareServiceClient()

Initializes a new instance of the ShareServiceClient class for mocking.

protected ShareServiceClient()

ShareServiceClient(string)

Initializes a new instance of the ShareServiceClient class.

public ShareServiceClient(string connectionString)

Parameters

connectionString string

A connection string includes the authentication information required for your application to access data in an Azure Storage account at runtime.

For more information, Configure Azure Storage connection strings.

ShareServiceClient(string, ShareClientOptions)

Initializes a new instance of the ShareServiceClient class.

public ShareServiceClient(string connectionString, ShareClientOptions options)

Parameters

connectionString string

A connection string includes the authentication information required for your application to access data in an Azure Storage account at runtime.

For more information, Configure Azure Storage connection strings.

options ShareClientOptions

Optional client options that define the transport pipeline policies for authentication, retries, etc., that are applied to every request.

ShareServiceClient(Uri, AzureSasCredential, ShareClientOptions)

Initializes a new instance of the ShareServiceClient class.

public ShareServiceClient(Uri serviceUri, AzureSasCredential credential, ShareClientOptions options = null)

Parameters

serviceUri Uri

A Uri referencing the file service. Must not contain shared access signature, which should be passed in the second parameter.

credential AzureSasCredential

The shared access signature credential used to sign requests.

options ShareClientOptions

Optional client options that define the transport pipeline policies for authentication, retries, etc., that are applied to every request.

Remarks

This constructor should only be used when shared access signature needs to be updated during lifespan of this client.

ShareServiceClient(Uri, TokenCredential, ShareClientOptions)

Initializes a new instance of the ShareServiceClient class.

Note that service-level operations do not support token credential authentication. This constructor exists to allow the construction of a ShareServiceClient that can be used to derive a ShareClient that has token credential authentication.

Also note that ShareTokenIntent is currently required for token authentication.

public ShareServiceClient(Uri serviceUri, TokenCredential credential, ShareClientOptions options = null)

Parameters

serviceUri Uri

A Uri referencing the file service.

credential TokenCredential

The token credential used to sign requests.

options ShareClientOptions

Optional client options that define the transport pipeline policies for authentication, retries, etc., that are applied to every request.

ShareServiceClient(Uri, ShareClientOptions)

Initializes a new instance of the ShareServiceClient class.

public ShareServiceClient(Uri serviceUri, ShareClientOptions options = null)

Parameters

serviceUri Uri

A Uri referencing the file service.

options ShareClientOptions

Optional client options that define the transport pipeline policies for authentication, retries, etc., that are applied to every request.

ShareServiceClient(Uri, StorageSharedKeyCredential, ShareClientOptions)

Initializes a new instance of the ShareServiceClient class.

public ShareServiceClient(Uri serviceUri, StorageSharedKeyCredential credential, ShareClientOptions options = null)

Parameters

serviceUri Uri

A Uri referencing the file service.

credential StorageSharedKeyCredential

The shared key credential used to sign requests.

options ShareClientOptions

Optional client options that define the transport pipeline policies for authentication, retries, etc., that are applied to every request.

Properties

AccountName

Gets the Storage account name corresponding to the file service client.

public virtual string AccountName { get; }

Property Value

string

CanGenerateAccountSasUri

Determines whether the client is able to generate a SAS. If the client is authenticated with a Azure.Storage.StorageSharedKeyCredential.

public virtual bool CanGenerateAccountSasUri { get; }

Property Value

bool

Uri

Gets the file service's primary Uri endpoint.

public virtual Uri Uri { get; }

Property Value

Uri

Methods

CreateShare(string, ShareCreateOptions, CancellationToken)

The CreateShare(string, ShareCreateOptions, CancellationToken) operation creates a new share under the specified account. If a share with the same name already exists, the operation fails.

For more information, see Create Share.

public virtual Response<ShareClient> CreateShare(string shareName, ShareCreateOptions options, CancellationToken cancellationToken = default)

Parameters

shareName string

The name of the share to create.

options ShareCreateOptions

Optional parameters.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Response<ShareClient>

A Azure.Response<> referencing the newly created share.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

CreateShareAsync(string, ShareCreateOptions, CancellationToken)

The CreateShare(string, ShareCreateOptions, CancellationToken) operation creates a new share under the specified account. If a share with the same name already exists, the operation fails.

For more information, see Create Share.

public virtual Task<Response<ShareClient>> CreateShareAsync(string shareName, ShareCreateOptions options, CancellationToken cancellationToken = default)

Parameters

shareName string

The name of the share to create.

options ShareCreateOptions

Optional parameters.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Task<Response<ShareClient>>

A Azure.Response<> referencing the newly created share.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

DeleteShare(string, ShareDeleteOptions, CancellationToken)

Marks the specified share or share snapshot for deletion. The share or share snapshot and any files contained within it are later deleted during garbage collection which could take several minutes.

Currently, this method will always delete snapshots. There's no way to specify a separate value for x-ms-delete-snapshots.

For more information, see Delete Share.

public virtual Response DeleteShare(string shareName, ShareDeleteOptions options, CancellationToken cancellationToken = default)

Parameters

shareName string

The name of the share to delete.

options ShareDeleteOptions

Optional parameters.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Response

A Azure.Response on successfully marking for deletion.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

DeleteShareAsync(string, ShareDeleteOptions, CancellationToken)

Marks the specified share or share snapshot for deletion. The share or share snapshot and any files contained within it are later deleted during garbage collection which could take several minutes.

Currently, this method will always delete snapshots. There's no way to specify a separate value for x-ms-delete-snapshots.

For more information, see Delete Share.

public virtual Task<Response> DeleteShareAsync(string shareName, ShareDeleteOptions options, CancellationToken cancellationToken = default)

Parameters

shareName string

The name of the share to delete.

options ShareDeleteOptions

Optional parameters.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Task<Response>

A Azure.Response on successfully marking for deletion.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

GenerateAccountSasUri(AccountSasBuilder)

The GenerateAccountSasUri(AccountSasBuilder) returns a Uri that generates a Share Account Shared Access Signature (SAS) based on the Client properties and builder passed. The SAS is signed by the shared key credential of the client.

To check if the client is able to sign a Service Sas see CanGenerateAccountSasUri.

For more information, see Constructing an Account SAS.

public Uri GenerateAccountSasUri(AccountSasBuilder builder)

Parameters

builder AccountSasBuilder

Used to generate a Shared Access Signature (SAS)

Returns

Uri

A ShareSasBuilder on successfully deleting.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

GenerateAccountSasUri(AccountSasPermissions, DateTimeOffset, AccountSasResourceTypes)

The GenerateAccountSasUri(AccountSasPermissions, DateTimeOffset, AccountSasResourceTypes) returns a Uri that generates a Share Account Shared Access Signature (SAS) based on the Client properties and parameters passed. The SAS is signed by the shared key credential of the client.

To check if the client is able to sign a Service Sas see CanGenerateAccountSasUri.

For more information, see Constructing an Account SAS.

public Uri GenerateAccountSasUri(AccountSasPermissions permissions, DateTimeOffset expiresOn, AccountSasResourceTypes resourceTypes)

Parameters

permissions AccountSasPermissions

Required. Specifies the list of permissions to be associated with the SAS. See Azure.Storage.Sas.AccountSasPermissions.

expiresOn DateTimeOffset

Required. The time at which the shared access signature becomes invalid.

resourceTypes AccountSasResourceTypes

Specifies the resource types associated with the shared access signature. The user is restricted to operations on the specified resources. See Azure.Storage.Sas.AccountSasResourceTypes.

Returns

Uri

A Uri containing the SAS Uri.

Remarks

A Exception will be thrown if a failure occurs.

GetProperties(CancellationToken)

The GetProperties(CancellationToken) operation gets the properties of a storage account’s file service, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

For more information, see Get File Service Properties.

public virtual Response<ShareServiceProperties> GetProperties(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Response<ShareServiceProperties>

A Azure.Response<> describing the service properties.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

GetPropertiesAsync(CancellationToken)

The GetPropertiesAsync(CancellationToken) operation gets the properties of a storage account’s file service, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

For more information, see Get File Service Properties.

public virtual Task<Response<ShareServiceProperties>> GetPropertiesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Task<Response<ShareServiceProperties>>

A Azure.Response<> describing the service properties.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

GetShareClient(string)

Create a new ShareClient object by appending shareName to the end of Uri. The new ShareClient uses the same request policy pipeline as the ShareServiceClient.

public virtual ShareClient GetShareClient(string shareName)

Parameters

shareName string

The name of the share to reference.

Returns

ShareClient

A ShareClient for the desired share.

GetShares(ShareTraits, ShareStates, string, CancellationToken)

The GetShares(ShareTraits, ShareStates, string, CancellationToken) operation returns an async sequence of the shares in the storage account. Enumerating the shares may make multiple requests to the service while fetching all the values.

For more information, see List Shares.

public virtual Pageable<ShareItem> GetShares(ShareTraits traits = ShareTraits.None, ShareStates states = ShareStates.None, string prefix = null, CancellationToken cancellationToken = default)

Parameters

traits ShareTraits

Specifies traits to include in the ShareItems.

states ShareStates

Specifies states to include when listing shares.

prefix string

String that filters the results to return only shares whose name begins with the specified prefix.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Pageable<ShareItem>

An IEnumerable<T> of Azure.Response<> describing the shares in the storage account.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

GetSharesAsync(ShareTraits, ShareStates, string, CancellationToken)

The GetSharesAsync(ShareTraits, ShareStates, string, CancellationToken) operation returns an async collection of the shares in the storage account. Enumerating the shares may make multiple requests to the service while fetching all the values.

For more information, see List Shares.

public virtual AsyncPageable<ShareItem> GetSharesAsync(ShareTraits traits = ShareTraits.None, ShareStates states = ShareStates.None, string prefix = null, CancellationToken cancellationToken = default)

Parameters

traits ShareTraits

Specifies traits to include in the ShareItems.

states ShareStates

Specifies states to include when listing shares.

prefix string

String that filters the results to return only shares whose name begins with the specified prefix.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

AsyncPageable<ShareItem>

A Azure.AsyncPageable<> describing the shares in the storage account.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

SetProperties(ShareServiceProperties, CancellationToken)

The SetProperties(ShareServiceProperties, CancellationToken) operation sets properties for a storage account’s File service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings. You can also use this operation to set the default request version for all incoming requests to the File service that do not have a version specified.

For more information, see Set File Service Properties.

public virtual Response SetProperties(ShareServiceProperties properties, CancellationToken cancellationToken = default)

Parameters

properties ShareServiceProperties

The file service properties.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Response

A Azure.Response if the operation was successful.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

SetPropertiesAsync(ShareServiceProperties, CancellationToken)

The SetPropertiesAsync(ShareServiceProperties, CancellationToken) operation sets properties for a storage account’s File service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings. You can also use this operation to set the default request version for all incoming requests to the File service that do not have a version specified.

For more information, see Set File Service Properties.

public virtual Task<Response> SetPropertiesAsync(ShareServiceProperties properties, CancellationToken cancellationToken = default)

Parameters

properties ShareServiceProperties

The file service properties.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Task<Response>

A Azure.Response if the operation was successful.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

UndeleteShare(string, string, CancellationToken)

Restores a previously deleted Share. This API is only functional is Share Soft Delete is enabled for the storage account associated with the share.

public virtual Response<ShareClient> UndeleteShare(string deletedShareName, string deletedShareVersion, CancellationToken cancellationToken = default)

Parameters

deletedShareName string

The name of the share to restore.

deletedShareVersion string

The version of the share to restore.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Response<ShareClient>

A Azure.Response<> pointed at the restored Share.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs.

UndeleteShareAsync(string, string, CancellationToken)

Restores a previously deleted Share. This API is only functional is Share Soft Delete is enabled for the storage account associated with the share.

public virtual Task<Response<ShareClient>> UndeleteShareAsync(string deletedShareName, string deletedShareVersion, CancellationToken cancellationToken = default)

Parameters

deletedShareName string

The name of the share to restore.

deletedShareVersion string

The version of the share to restore.

cancellationToken CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Task<Response<ShareClient>>

A Azure.Response<> pointed at the restored Share.

Remarks

A Azure.RequestFailedException will be thrown if a failure occurs