Azure / Azure/azure-powershell
[Az.Storage] References of "Microsoft.Azure.Storage.File" in File cmdlets will be removed
- Dominant language
- C#
- Stars
- 4.8k
- Forks
- 4.3k
- Avg merge
- 3d 14h
- Merged PRs (30d)
- 54
Description
### 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](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.16.0) 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)](https://www.powershellgallery.com/packages/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:
```powershell
# 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:
```powershell
# 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:
```powershell
$dir = New-AzStorageDirectory -ShareName testshare1 -Path -Context
# Check if the directory exists
$dir.CloudDirectory.Exists()
````
Updated usages with v12 SDK:
```powershell
$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:
```powershell
$file = Get-AzStorageFile -Share $sharename -Path $filepath -Context $ctx
# Set metadata of a file
$file.CloudFile.SetMetadata(...)
```
Updated usages with v12 SDK:
```powershell
$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:
```powershell
$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:
```powershell
$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:
```powershell
# 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:
```powershell
# 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:
```powershell
```
Updated usages with v12 SDK:
```powershell
```
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'`.
3. 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:
```powershell
# 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:
```powershell
# 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
```
Contributor guide
Research direction
The issue names the File cmdlets, including Get-AzStorageFile, New-AzStorageShare, Start-AzStorageFileCopy, and related commands, but no source files or tests. Start by locating those cmdlet entry points and tracing their v11 Microsoft.Azure.Storage.File inputs and outputs; done would require a defined implementation scope and tests for the listed v12 SDK behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, powershell
- Domain
- cli, cloud
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100