Quickstart: Create and manage an Azure file share with Azure PowerShell

This guide walks you through the basics of working with Azure file shares with PowerShell. Azure file shares are just like other file shares, but stored in the cloud and backed by the Azure platform. Azure File shares support the industry standard SMB protocol and enable file sharing across multiple machines, applications, and instances.

If you don't have an Azure subscription, create a free account before you begin.

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.

Open Azure Cloud Shell

Azure Cloud Shell is an interactive shell environment hosted in Azure and used through your browse. Azure Cloud Shell allows you to use either bash or PowerShell shells to run a variety of tools to work with Azure services. Azure Cloud Shell comes pre-installed with the commands to allow you to run the content of this article without having to install anything on your local environment.

To run any code contained in this article on Azure Cloud Shell, open a Cloud Shell session, use the Copy button on a code block to copy the code, and paste it into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS. Pasted text is not automatically executed, so press Enter to run code.

You can launch Azure Cloud Shell with:

Option Example/Link
Select Try It in the upper-right corner of a code block. This doesn't automatically copy text to Cloud Shell. Example of Try It for Azure Cloud Shell
Open Azure Cloud Shell in your browser.
Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal. Cloud Shell button in the Azure portal

If you would like to install and use the PowerShell locally, this guide requires the Azure PowerShell module Az version 0.7 or later. To find out which version of the Azure PowerShell module you are running, execute Get-Module -ListAvailable Az. If you need to upgrade, see Install Azure PowerShell module. If you are running PowerShell locally, you also need to run Login-AzAccount to login to your Azure account.

Create a resource group

A resource group is a logical container into which Azure resources are deployed and managed. If you don't already have an Azure resource group, you can create a new one with the New-AzResourceGroup cmdlet.

The following example creates a resource group named myResourceGroup in the East US region:

New-AzResourceGroup `
    -Name myResourceGroup `
    -Location EastUS

Create a storage account

A storage account is a shared pool of storage you can use to deploy Azure file shares, or other storage resources such as blobs or queues. A storage account can contain an unlimited number of shares, and a share can store an unlimited number of files, up to the capacity limits of the storage account.

This example creates a storage account using the New-AzStorageAccount cmdlet. The storage account is named mystorageaccount<random number> and a reference to that storage account is stored in the variable $storageAcct. Storage account names must be unique, so use Get-Random to append a number to the name to make it unique.

$storageAcct = New-AzStorageAccount `
                  -ResourceGroupName "myResourceGroup" `
                  -Name "mystorageacct$(Get-Random)" `
                  -Location eastus `
                  -SkuName Standard_LRS 

Create an Azure file share

Now you can create your first Azure file share. You can create a file share using the New-AzStorageShare cmdlet. This example creates a share named myshare.

New-AzStorageShare `
   -Name myshare `
   -Context $storageAcct.Context

Share names need to be all lower-case letters, numbers, and single hyphens but cannot start with a hyphen. For complete details about naming file shares and files, see Naming and Referencing Shares, Directories, Files, and Metadata.

Use your Azure file share

Azure Files provides two methods of working with files and folders within your Azure file share: the industry standard Server Message Block (SMB) protocol and the File REST protocol.

To mount a file share with SMB, see the following document based on your OS:

Using an Azure file share with the File REST protocol

It is possible work directly with the File REST protocol directly (i.e. handcrafting REST HTTP calls yourself), but the most common way to use the File REST protocol is to use the Azure PowerShell module, the Azure CLI, or an Azure Storage SDK, all of which provide a nice wrapper around the File REST protocol in the scripting/programming language of your choice.

In most cases, you will use your Azure file share over the SMB protocol, as this allows you to use the existing applications and tools you expect to be able to use, but there are several reasons why it is advantageous to use the File REST API rather than SMB, such as:

  • You are browsing your file share from the PowerShell Cloud Shell (which cannot mount file shares over SMB).
  • You need to execute a script or application from a client which cannot mount an SMB shares, such as on-premises clients which do not have port 445 unblocked.
  • You are taking advantage of serverless resources, such as Azure Functions.

The following examples show how to use the Azure PowerShell module to manipulate your Azure file share with the File REST protocol.

Create directory

To create a new directory named myDirectory at the root of your Azure file share, use the New-AzStorageDirectory cmdlet.

New-AzStorageDirectory `
   -Context $storageAcct.Context `
   -ShareName "myshare" `
   -Path "myDirectory"

Upload a file

To demonstrate how to upload a file using the Set-AzStorageFileContent cmdlet, we first need to create a file inside your PowerShell Cloud Shell's scratch drive to upload.

This example puts the current date and time into a new file on your scratch drive, then uploads the file to the file share.

# this expression will put the current date and time into a new file on your scratch drive
Get-Date | Out-File -FilePath "C:\Users\ContainerAdministrator\CloudDrive\SampleUpload.txt" -Force

# this expression will upload that newly created file to your Azure file share
Set-AzStorageFileContent `
   -Context $storageAcct.Context `
   -ShareName "myshare" `
   -Source "C:\Users\ContainerAdministrator\CloudDrive\SampleUpload.txt" `
   -Path "myDirectory\SampleUpload.txt"

If you're running PowerShell locally, you should substitute C:\Users\ContainerAdministrator\CloudDrive\ with a path that exists on your machine.

After uploading the file, you can use Get-AzStorageFile cmdlet to check to make sure that the file was uploaded to your Azure file share.

Get-AzStorageFile -Context $storageAcct.Context -ShareName "myshare" -Path "myDirectory" 

Download a file

You can use the Get-AzStorageFileContent cmdlet to download a copy of the file you just uploaded to the scratch drive of your Cloud Shell.

# Delete an existing file by the same name as SampleDownload.txt, if it exists because you've run this example before.
Remove-Item `
     -Path "C:\Users\ContainerAdministrator\CloudDrive\SampleDownload.txt" `
     -Force `
     -ErrorAction SilentlyContinue

Get-AzStorageFileContent `
    -Context $storageAcct.Context `
    -ShareName "myshare" `
    -Path "myDirectory\SampleUpload.txt" ` 
    -Destination "C:\Users\ContainerAdministrator\CloudDrive\SampleDownload.txt"

After downloading the file, you can use the Get-ChildItem to see that the file has been downloaded to your PowerShell Cloud Shell's scratch drive.

Get-ChildItem -Path "C:\Users\ContainerAdministrator\CloudDrive"

Copy files

One common task is to copy files from one file share to another file share, or to/from an Azure Blob storage container. To demonstrate this functionality, you can create a new share and copy the file you just uploaded over to this new share using the Start-AzStorageFileCopy cmdlet.

New-AzStorageShare `
    -Name "myshare2" `
    -Context $storageAcct.Context
  
New-AzStorageDirectory `
   -Context $storageAcct.Context `
   -ShareName "myshare2" `
   -Path "myDirectory2"

Start-AzStorageFileCopy `
    -Context $storageAcct.Context `
    -SrcShareName "myshare" `
    -SrcFilePath "myDirectory\SampleUpload.txt" `
    -DestShareName "myshare2" `
    -DestFilePath "myDirectory2\SampleCopy.txt" `
    -DestContext $storageAcct.Context

Now, if you list the files in the new share, you should see your copied file.

Get-AzStorageFile -Context $storageAcct.Context -ShareName "myshare2" -Path "myDirectory2" 

While the Start-AzStorageFileCopy cmdlet is convenient for ad hoc file moves between Azure file shares and Azure Blob storage containers, we recommend AzCopy for larger moves (in terms of number or size of files being moved). Learn more about AzCopy for Windows and AzCopy for Linux. AzCopy must be installed locally - it is not available in Cloud Shell.

Create and manage share snapshots

One additional useful task you can do with an Azure file share is to create share snapshots. A snapshot preserves a point in time for an Azure file share. Share snapshots are similar to operating system technologies you may already be familiar with such as:

$share = Get-AzStorageShare -Context $storageAcct.Context -Name "myshare"
$snapshot = $share.Snapshot()

Browse share snapshots

You can browse the contents of the share snapshot by passing the snapshot reference ($snapshot) to the -Share parameter of the Get-AzStorageFile cmdlet.

Get-AzStorageFile -Share $snapshot

List share snapshots

You can see the list of snapshots you've taken for your share with the following command.

Get-AzStorageShare -Context $storageAcct.Context | Where-Object { $_.Name -eq "myshare" -and $_.IsSnapshot -eq $true }

Restore from a share snapshot

You can restore a file by using the Start-AzStorageFileCopy command we used before. For the purposes of this quickstart, we'll first delete our SampleUpload.txt file we previously uploaded so we can restore it from the snapshot.

# Delete SampleUpload.txt
Remove-AzStorageFile `
    -Context $storageAcct.Context `
    -ShareName "myshare" `
    -Path "myDirectory\SampleUpload.txt"
 # Restore SampleUpload.txt from the share snapshot
Start-AzStorageFileCopy `
    -SrcShare $snapshot `
    -SrcFilePath "myDirectory\SampleUpload.txt" `
    -DestContext $storageAcct.Context `
    -DestShareName "myshare" `
    -DestFilePath "myDirectory\SampleUpload.txt"

Delete a share snapshot

You can delete a share snapshot by using the Remove-AzStorageShare cmdlet, with the variable containing the $snapshot reference to the -Share parameter.

Remove-AzStorageShare -Share $snapshot

Clean up resources

When you are done, you can use the Remove-AzResourceGroup cmdlet to remove the resource group and all related resources.

Remove-AzResourceGroup -Name myResourceGroup

You can alternatively remove resources one by one:

  • To remove the Azure file shares we created for this quickstart.

    Get-AzStorageShare -Context $storageAcct.Context | Where-Object { $_.IsSnapshot -eq $false } | ForEach-Object { 
        Remove-AzStorageShare -Context $storageAcct.Context -Name $_.Name
    }
    
  • To remove the storage account itself (this will implicitly remove the Azure file shares we created as well as any other storage resources you may have created such as an Azure Blob storage container).

    Remove-AzStorageAccount -ResourceGroupName $storageAcct.ResourceGroupName -Name $storageAcct.StorageAccountName
    

Next steps