PowerShell for Azure File Sync

While deploying Azure File Sync for a customer I’ve come across some useful PowerShell commands. Some are directly from Microsoft while others have been created by me to handle scenarios that may not be customer specific.

View file sync error report

When Azure File Sync is installed it includes tools to investigate the reason for tiles not syncing. If the portal states that there are files not being synced connect to the affected server endpoint and run the following PowerShell-cmdlets.

Set-Location $env:ProgramFiles\Azure\StorageSyncAgent
.\FileSyncErrorsReport.ps1

This will run the built in sync error report for all sync groups on the server. If you’d prepare to export the errors to a CSV-file just add a switch as below.

Set-Location $env:ProgramFiles\Azure\StorageSyncAgent
.\FileSyncErrorsReport.ps1 -CsvPath C:\temp\SyncErrors.csv

If you live in a country using characters looking something like this å,ä,ö you’ll probably end up with a error report where these characters are replaced by question marks (?). This can however be easily solved by modifying row 910 in FileSyncErrorsReport.ps1.

#Replace this
$ResultTable | Select-Object SyncGroup,SyncDirection,SessionId,SessionTime,SessionSyncDirection,Operation,PersistentError,ItemPath,ErrorCode,ErrorDescription,InvalidCharCode,InvalidCharPosition,InvalidCharDescription | Export-Csv -NoTypeInformation -Path $CsvPath

#With this
$ResultTable | Select-Object SyncGroup,SyncDirection,SessionId,SessionTime,SessionSyncDirection,Operation,PersistentError,ItemPath,ErrorCode,ErrorDescription,InvalidCharCode,InvalidCharPosition,InvalidCharDescription | Export-Csv -NoTypeInformation -Path $CsvPath -Encoding UTF8

Resolving files with invalid characters

Since writing this article Microsoft have published a script to handle invalid characters in folder and file names, check it out on GitHub.

The major issue I encountered during the migration was files not syncing due to invalid characters in the file names returned in the report above as error code 0x8007007b. While the root cause is unknown this script will quickly remove the illegal characters from the file names.

$BasePath = "D:\Data" #Path where files with illegal characters are located

#Find all files in the path containing the illegal characted
$Items = Get-ChildItem $BasePath -Name *�*  -Recurse

#Rename the files replacing the illegal character
$Items | foreach {

$Path = $BasePath + $_

$Filename = $Path -split '\',-1,'SimpleMatch'
$Filename = $Filename[$Filename.Count-1]
$Filename = $Filename -replace "�",""

Rename-Item -Path $Path -NewName $Filename

}

If the files still appear in the sync error report a few minutes later I found that restarting the “Storage Sync Agent”-service helped.

Download all tiered files

This is primarily useful if you’re disabling tiering on a server or removing Azure File Sync for a specific share or all together.

Using the Azure Portal, disable tiering for the server endpoint. Connect to the server and run the following PowerShell command to download all files to the local server.

$Path = "D:\Data" #Local path of the files to download

Set-Location $env:ProgramFiles\Azure\StorageSyncAgent
Import-Module ".\StorageSync.Management.ServerCmdlets.dll"
Invoke-StorageSyncFileRecall -Path $Path

Force tiering of a specific file or folder

A tiered file is not actually available on the server endpoint. It’s content will automatically be made available if requested. If you have files that take up space on your server and want to free up that space you can use the following code. When applied to a directory the script will recursively tier all files in that folder and sub-folders.

$Path = "D:\Data" #Local path of the files you want to tier

Set-Location $env:ProgramFiles\Azure\StorageSyncAgent
Import-Module ".\StorageSync.Management.ServerCmdlets.dll"
Invoke-StorageSyncCloudTiering -Path $Path

Check what application is tiering files on your server

If you start to see sync activity that is not expected it may be worth investigating further. Monitoring, backup or anti-virus may be tiering files in a way that will negatively impact performance and cause additional cost. The following command will return the 500 latest files that were tiered.

The primary application causing a file to be tiered on a general purpose file server should be “Access over SMB/System process”, by un-commenting the section in the script these events can be excluded from the output.

Set-Location $env:ProgramFiles\Azure\StorageSyncAgent
Import-Module ".\StorageSync.Management.ServerCmdlets.dll"

$RC = Get-StorageSyncFileRecallResult
$RC <# | where {$_.ProcessName -ne "Access over SMB/System process"} #> | ft EventTime, ProcessName, FileName 

Apply a scheduled network limit for AFS operations

The AFS sync agent is capable of delivering some pretty impressive transfer speeds, especially when onboarding a new server. Depending on your infrastructure this may be an issue, luckily Microsoft provides a simple solution to the problem. By applying a scheduled network limit you can ensure that the data transfer doesn’t impact the general file server performance during office hours.

#This example will limit the bandwith used by AFS to 50Mbps between 6 and 18 on weekdays.

$SpeedLimit = 50000 #Network speed limit in kbps

Set-Location $env:ProgramFiles\Azure\StorageSyncAgent
Import-Module ".\StorageSync.Management.ServerCmdlets.dll"

New-StorageSyncNetworkLimit -Day Monday, Tuesday, Wednesday, Thursday, Friday -StartHour 6 -EndHour 18 -LimitKbps $SpeedLimit

Enable self service file restore using previous versions

Starting with version 9 of the AFS agent previous versions via volume shadow copy can be enabled using PowerShell. After enabling the feature ensure a reasonable amount of storage is available for the VSS snapshots by right-clicking the volume and selecting “Configure Shadow Copies…”

$DriveLetter = "D:" #Drive letter of the target volume

Set-Location $env:ProgramFiles\Azure\StorageSyncAgent
Import-Module ".\StorageSync.Management.ServerCmdlets.dll"

Enable-StorageSyncSelfServiceRestore $DriveLetter