[Az.Storage] References of "Microsoft.Azure.Storage.File" in File cmdlets will be removed

[yifanz7]

Description

Overview

In the upcoming release in November, references of v11 SDK "Microsoft.Azure.Storage.File" will be removed from File cmdlets. v12 SDK Azure.Storage.Files.Shares will be used instead. This will bring some breaking changes to the File cmdlets as a result and customers will need to update to use v12 SDK APIs instead.

Currently we have released a preview Az.Storage module (Az.Storage 7.4.1-preview) that contains all the upcoming changes that customers can download and give it a try.

Upcoming Breaking Changes

1. v11 SDK objects will be removed from outputs of File cmdlets. Customers will need to use v12 objects in the outputs instead in order to access .NET SDK methods. Using .NET SDK APIs with v11 objects will result in the exception of You cannot call a method on a null-valued expression.

   1. CloudFileShare will be removed from outputs of the following cmdlets: Get-AzStorageFile, New-AzStorageShare, Get-AzStorageShare, Remove-AzStorageShare, New-AzStorageDirectory, Remove-AzStorageDirectory. Customers should use child property ShareClient instead. Some samples of the original and updated usages:

      Original usages with v11 SDK:

      # Retrieve a specific share 
      $share = Get-AzStorageShare -Name $shareName -Context $ctx 
      
      # Create a snapshot of the share 
      $share.CloudFileShare.Snapshot()

      Updated usages with v12 SDK:

      # Retrieve a specific share 
      $share = Get-AzStorageShare -Name $shareName -Context $ctx
      
      # Create a snapshot of the share 
      $share.ShareClient.CreateSnapshot()

      For all the .NET SDK methods available for ShareClient, please refer to https://learn.microsoft.com/en-us/dotnet/api/azure.storage.files.shares.shareclient?view=azure-dotnet

   2. CloudFileDirectory will be removed from outputs of the following cmdlets: Get-AzStorageFile, New-AzStorageDirectory, Remove-AzStorageDirectory. Customers should use child property ShareDirectoryClient instead. Some samples of the original and updated usages:
      Original usages with v11 SDK:

      $dir = New-AzStorageDirectory -ShareName testshare1 -Path -Context 
      # Check if the directory exists 
      $dir.CloudDirectory.Exists()

      Updated usages with v12 SDK:

      $dir = New-AzStorageDirectory -ShareName testshare1 -Path -Context 
      # Check if the directory exists 
      $dir.ShareDirectoryClient.Exists()

      For all the .NET SDK methods available for ShareDirectoryClient, please refer to https://learn.microsoft.com/en-us/dotnet/api/azure.storage.files.shares.sharedirectoryclient?view=azure-dotnet

   3. CloudFile will be removed from outputs of the following cmdlets: Get-AzStorageFile. Customers should use child property ShareFileClient instead. Some samples of the original and updated usages:
      Original usages with v11 SDK:

      $file = Get-AzStorageFile -Share $sharename -Path $filepath -Context $ctx 
      # Set metadata of a file 
      $file.CloudFile.SetMetadata(...)

      Updated usages with v12 SDK:

      $file = Get-AzStorageFile -Share $sharename -Path $filepath -Context $ctx 
      # Set metadata of a file 
      $file.ShareFileClient.SetMetadata(...)

      For all the .NET SDK methods available for ShareFileClient. please refer to https://learn.microsoft.com/en-us/dotnet/api/azure.storage.files.shares.sharefileclient?view=azure-dotnet

2. v11 SDK objects will be removed from inputs of File cmdlets. For cmdlets that accept objects as input parameters, v12 SDK should be used and will be mandatory. If customers pipe in the objects, the usages will not change. However, for those who input the v11 objects directly in the cmdlets, v12 objects should be used instead.

   1. The parameter Share (alias CloudFileShare) will be deprecated in the following cmdlets: Close-AzStorageFileHandle, Get-AzStorageFile, Get-AzStorageFileContent, Get-AzStorageFileHandle, Get-AzStorageShareStoredAccessPolicy, New-AzStorageDirectory, New-AzStorageFileSASToken, New-AzStorageShareStoredAccessPolicy, Remove-AzStorageDirectory, Remove-AzStorageFile, Remove-AzStorageShare, Set-AzStorageFileContent, Set-AzStorageShareQuota, Set-AzStorageShareStoredAccessPolicy, Start-AzStorageFileCopy. Parameter ShareClient should be used instead. Inputting Share parameter with v11 SDK object CloudFileShare will result in the exception of Parameter cannot be processed because the parameter name 'Share' is ambiguous. Some samples of the original and updated usages:

      Original usages with v11 SDK:

      $share = Get-AzStorageShare -Name $shareName -Context $ctx
      
      # Close file handle 
      Close-AzStorageFileHandle -Share $share.CloudFileShare -Path $path -CloseAll 
      # Get a specific file with a share client 
      Get-AzStorageFile -Share $share.CloudFileShare -Path $filepath -Context $ctx 
      # List files under a directory client 
      

      Updated usages with v12 SDK:

      $share = Get-AzStorageShare -Name $shareName -Context $ctx
      
      # Close file handle
      Close-AzStorageFileHandle -ShareClient $share.ShareClient -Path $path -CloseAll
      # Get a specific file with a share client 
      Get-AzStorageFile -ShareClient $share.ShareClient -Path $filepath -Context $ctx
      

   2. The parameter Directory (alias CloudFileDirectory) will be deprecated in the following cmdlets: Close-AzStorageFileHandle, Get-AzStorageFile, Get-AzStorageFileContent, Get-AzStorageFileHandle, New-AzStorageDirectory, Remove-AzStorageDirectory, Remove-AzStorageFile, Set-AzStorageFileContent. Parameter ShareDirectory should be used and will be required. Some samples of the original and updated usages:

      Original usages with v11 SDK:

      # List files under a directory client 
      $dir = Get-AzStorageFile -ShareName $sharename -Path $dirname -Context $ctx
      Get-AzStorageFile -Directory $dir.CloudFileDirectory -Context $ctx 

      Updated usages with v12 SDK:

      # List files under a directory client 
      $dir = Get-AzStorageFile -ShareName $sharename -Path $dirname -Context $ctx
      Get-AzStorageFile -ShareDirectoryClient $dir.ShareDirectoryClient -Context $ctx 

   3. The parameter File (alias CloudFile) will be deprecated in the following cmdlets: Get-AzStorageFileContent, Get-AzStorageFileHandle, New-AzStorageFileSASToken, Stop-AzStorageFileCopy. Parameter ShareFileClient shuold be used and will be required. Some sample of the original and updated usages:

      Original usages with v11 SDK:

      Updated usages with v12 SDK:

3. For cmdlet Start-AzStorageFileCopy, there will be two major changes:

   1. The type of SrcFile and DestFile will be changed from CloudFile to ShareFileClient. Inputting an object of type CloudFile will result in the exception of Cannot bind parameter 'SrcFile'. Cannot convert the "Microsoft.Azure.Storage.File.CloudFile" value of type "Microsoft.Azure.Storage.File.CloudFile" to type "Azure.Storage.Files.Shares.ShareFileClient".
      For paremeter SrcFile, parameter CloudFile will be deprecated. Using the deprecated parameter will result in the exception of A parameter cannot be found that matches parameter name 'CloudFile'.
   2. the parameter DestContext will be required when copying from file object or blob object to a destination file object. Copying without specifying the destination context will result in the exception of Start-AzStorageFileCopy : Could not get the destination storage context. Please pass in a storage context with /"-DestContext/" parameter (can be created with New-AzStorageContext cmdlet).

   For the changes mentioned above, here are some samples of the original and updates usages:
   Original usages with v11 SDK:

   # Copy from a source file to a destination file 
   $file = Get-AzStorageFile -ShareName $sharename -Path $srcfilepath -Context $ctx1 
   $destFile = Get-AzStorageFile -ShareName $sharename -Path $destfilepath -Context $ctx2 
   Start-AzStorageFileCopy -SrcFile $file.CloudFile -DestFile $destFile.CloudFile 
   
   # Copy from a source blob to a destination file 
   $blob = Get-AzStorageBlob -Blob $blobname -Container $containername -Context $ctx1 
    $destFile = Get-AzStorageFile -ShareName $sharename -Path $destfilepath -Context $ctx2 
   Start-AzStorageFileCopy -SrcBlob $blob.ICloudBlob -DestFile $destFile.CloudFile

   Updated usages with v12 SDK:

   # Copy from a source file to a destination file 
   $file = Get-AzStorageFile -ShareName $sharename1 -Path $srcfilepath -Context $ctx1 
   $destFile = Get-AzStorageFile -ShareName $sharename2 -Path $destfilepath -Context $ctx2
   Start-AzStorageFileCopy -SrcFile $file.ShareFileClient -DestFile $destFile.ShareFileClient -DestContext $ctx2
   
   # Copy from a source blob to a destination file 
   $blob = Get-AzStorageBlob -Blob $blobname -Container $containername -Context $ctx1 
   $destFile = Get-AzStorageFile -ShareName $sharename -Path $destfilepath -Context $ctx2 
   Start-AzStorageFileCopy -SrcBlob $blob.ICloudBlob -DestFile $destFile.ShareFileClient -DestContext $ctx2

[isra-fel]

@vidai-msft to check with Storage team if we want to publish migration guide of storage as a standalone document like this: https://learn.microsoft.com/en-us/powershell/azure/migrate-az-9.0.1-eventhub?view=azps-12.4.0

[yifanz7]

@isra-fel @vidai-msft Is there an instruction of how we can create a document like this and how we can update it? Thanks

[vidai-msft]

@yifanz7 there is no special instruction to generate the breaking change file. All we need is a markdown file with all the necessary breaking change migration guide info for Storage module.

[yifanz7]

@yifanz7 there is no special instruction to generate the breaking change file. All we need is a markdown file with all the necessary breaking change migration guide info for Storage module.

@vidai-msft Are we able to edit the migration guide by ourselves then?