feat: Allow a new upload session to be initiated as a single method call

[jskeet]

This allows the content length to be (optionally) specified, which is then propagated via X-Upload-Content-Length.

This is currently just a prototype for comment - I'd want to add integration tests, some unit tests, and obviously XML docs.

See #12034 for background.

[amanda-tarafa]

I think it would be useful to include the UploadObjectOptions as a parameter to these new methods, and then include the length in the UploadObjectOptions. We'd use the options slightly diferent in these methods, as the length field would be used to create the source (empty) stream instead of to modify the uploader, but I think that's fine, options are still surfaced in a consistent manner. And we would have to fail if both a stream and a lenght are provided, which is also fine I think. It's ugly implementation wise though.

Also, we could update this snippet to be simpler

[jskeet]

I think it would be useful to include the UploadObjectOptions as a parameter to these new methods, and then include the length in the UploadObjectOptions. We'd use the options slightly diferent in these methods, as the length field would be used to create the source (empty) stream instead of to modify the uploader, but I think that's fine, options are still surfaced in a consistent manner. And we would have to fail if both a stream and a lenght are provided, which is also fine I think. It's ugly implementation wise though.

Also, we could update this snippet to be simpler

I'll have a look at how much of UploadObjectOptions would actually be relevant. I thought most of it wouldn't be, but I could be wrong. Will look tomorrow.

[jskeet]

Right, having looked, I can see that UploadObjectOptions does indeed have a bunch of stuff in that would be relevant.

I think my personal preference would still be to have a separate method accepting the length and an UploadObjectOptions rather than putting the length into the options directly. I'll amend the PR with my preference for this, and we can then discuss it further. (I may have misunderstood your proposal.)

[amanda-tarafa]

Yep, this looks good.

[jskeet]

Great - will do all the rest of the work tomorrow, thanks !

[jskeet]

Okay, this is now ready for proper review.

It's currently only the async methods. I suspect we could add synchronous methods just by calling .ResultWithUnwrappedExceptions() - that's what we do in SignedUrlResumableUpload. (We may also want to provide the ability to specify a length in SignedUrlResumableUpload as well at some point.)

I'm happy to either add the sync methods in here, or wait until they're requested.

[amanda-tarafa]

Tiny nit only.

I'm fine with adding the sync versions later if there's demand for it.

[amanda-tarafa]

super nit: swap these two? I thought Visual Studio would catch that.

[jskeet]

Whoops, yes, will do.