[BUG] Incorrect documentation for BlockBlobClient.StageBlockAsync

[joshatendgame]

Library name and version

Azure.Storage.Blobs 12.16.0

Describe the bug

The documentation for BlockBlobClient.StageBlockAsync is wrong.

Expected behavior

It should not tell you to URL encode the base64BlockId parameter.

Actual behavior

It currently says to "Note that the Base64 string must be URL-encoded." This is erroneous as the library itself URL encodes this parameter, and the request will fail if the consuming code tries to do so itself.

Reproduction Steps

Read the documentation and observe that it is wrong.

Environment

No response

[github-actions]

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

[nickliu-msft]

Hi @joshatendgame, thanks for submitting this issue. I am not very familiar with the BlockBlobClient.StageBlockAsync code but from my tracing of it, I do not see the SDK encoding the base64BlockId param. Would you be able to show me where this is done?

[joshatendgame]

@nickliu-msft Hi Nick, thanks for your response. The encoding is done in BlockBlobRestClient.CreateStageBlockRequest (line 505 of that file in main currently) by passing true as the third argument to RawRequestUriBuilder.AppendQuery. (This eventually leads to a call to Uri.EscapeDataString inside RequestUriBuilder).

What is important is that if the consumer of BlockBlobClient follows the instructions to URI encode the parameter, then the URI-unsafe characters in the base64 encoded id (=, / and +) will be double escaped and the request will fail.

The documentation appears to have been copied from the same source as the documentation for the REST API here, for which it is appropriate as consumers of the raw REST API obviously need to escape the parameter: https://learn.microsoft.com/en-us/rest/api/storageservices/put-block

Hope that helps.