[BUG] Breaking change in UploadPages API

[madelson]

Library name and version

Azure.Storage.Blobs 12.14.0+

Describe the bug

In 12.13.1 and prior, the following line of code compiled:

PageBlobClient client = new(...);
// this line
client.UploadPages(new MemoryStream(new byte[BlobSize]), offset: 0, conditions: new PageBlobRequestConditions { LeaseId = leaseId });

However, starting in 12.14.0, this line fails to compile with the following error message:

C:\...\MyFile.cs(113,26): error CS7036: There is no argument given that corresponds to the required parameter 'transactionalContentHash' of 'PageBlobClient.UploadPages(Stream, long, byte[], PageBlobRequestConditions, IProgress<long>, CancellationToken)' [C:\...\MyProject.csproj::TargetFramework=net8.0]

This change doesn't seem to be reflected in the docs.

Expected behavior

The original code should still compile.

Actual behavior

Compiler error

Reproduction Steps

Make a project with Azure.Storage.Blobs 12.13.1 and the following code:

void Main()
{
	PageBlobClient client = new("", "", "");
	client.UploadPages(new MemoryStream(new byte[1]), offset: 0, conditions: new PageBlobRequestConditions());
}

This will compile without error.

Then, update to 12.19.1 => it will no longer compile.

Environment

.NET SDK:
 Version:           8.0.100
 Commit:            57efcf1350
 Workload version:  8.0.100-manifests.8d38d0cc

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.22621
 OS Platform: Windows
 RID:         win-x64
 Base Path:   C:\Program Files\dotnet\sdk\8.0.100\

.NET workloads installed:
 Workload version: 8.0.100-manifests.8d38d0cc
There are no installed workloads to display.

Host:
  Version:      8.0.0
  Architecture: x64
  Commit:       5535e31a71

.NET SDKs installed:
  8.0.100 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 8.0.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 6.0.26 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.0 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.WindowsDesktop.App 6.0.26 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 8.0.0 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Other architectures found:
  x86   [C:\Program Files (x86)\dotnet]
    registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]

Environment variables:
  Not set

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download

VS 17.8.2, also reproduces on the command line with dotnet build.

[github-actions]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @xgithubtriage.

[jaschrep-msft]

Hi @madelson. Thank you for reaching out. I can validate this behavior. However, I'm afraid this isn't an issue we plan to fix.

Early on in this major version, the library started shifting methods over from ever-expanding overloads to an "options bag" overload. When this happens, the overload that gets the optional parameter privilege shifts. While the options bag strategy is designed to minimize the frequency of this, it can't fully avoid it.

Azure SDK strives to avoid breaking changes when recompiling. However, such a break is preferred over a binary breaking change. Were you to upgrade binaries without recompiling, you would not encounter this issue, since the concept of default parameters is removed at compile time.

I recognize this is not the desired answer, but this is our strategy moving forward with the modern Azure SDK. In this specific case, you can either fill in the missing parameters, or move to the overload that accepts an instance of PageBlobUploadPagesOptions. They are functionally equivalent.

[madelson]

I really appreciate the detailed explanation. Knowing that this is the intended behavior going forward, adapting to it should not be difficult