Skip to content

Commit 9647310

Browse files
GarrettBeattyGarrettBeatty
authored
Doc updates (#4229)
1 parent 2c4f2ac commit 9647310

File tree

3 files changed

+169
-4
lines changed

3 files changed

+169
-4
lines changed

‎sdk/src/Services/S3/Custom/Transfer/TransferUtilityDownloadDirectoryRequest.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -318,6 +318,7 @@ internal bool IsSetUnmodifiedSinceDate()
318318
/// Specifies if multiple files will be downloaded concurrently.
319319
/// The number of concurrent web requests used is controlled
320320
/// by the TransferUtilityConfig.ConcurrencyLevel property.
321+
/// The default value is <c>false</c>.
321322
/// </summary>
322323
#if BCL || NETSTANDARD
323324
public

‎sdk/src/Services/S3/Custom/Transfer/_async/ITransferUtility.async.cs‎

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -343,6 +343,26 @@ public partial interface ITransferUtility : IDisposable
343343
/// <item><description>Downloaded parts are written directly to the file as they arrive</description></item>
344344
/// </list>
345345
/// <para>
346+
/// <b>Multipart Download Strategy:</b>
347+
/// </para>
348+
/// <para>
349+
/// The <see cref="BaseDownloadRequest.MultipartDownloadType"/> property controls how parts are downloaded (default: <c>MultipartDownloadType.PART</c>):
350+
/// </para>
351+
/// <list type="bullet">
352+
/// <item><description><b>PART (default)</b>: Uses the original part boundaries from when the object was uploaded with multipart upload.
353+
/// This is more efficient as it aligns with S3's internal part structure, but <b>requires that the object was uploaded using multipart upload</b>.
354+
/// The <see cref="BaseDownloadRequest.PartSize"/> property is ignored in this mode.</description></item>
355+
/// <item><description><b>RANGE</b>: Uses range-based downloads with configurable part sizes via the <see cref="BaseDownloadRequest.PartSize"/> property.
356+
/// This works with any object (whether uploaded as single-part or multipart) and provides more flexibility in controlling download part sizes.</description></item>
357+
/// </list>
358+
/// <para>
359+
/// <b>When to use PART vs RANGE:</b>
360+
/// </para>
361+
/// <list type="bullet">
362+
/// <item><description>Use <b>PART</b> mode (default) when you know the object was uploaded using multipart upload and want optimal performance.</description></item>
363+
/// <item><description>Use <b>RANGE</b> mode when the object's upload method is unknown, when you need specific part sizes, or when downloading objects that were uploaded as a single part.</description></item>
364+
/// </list>
365+
/// <para>
346366
/// <b>Configuration Options:</b>
347367
/// </para>
348368
/// <para>
@@ -393,6 +413,26 @@ public partial interface ITransferUtility : IDisposable
393413
/// <item><description>Downloaded parts are written directly to the file as they arrive</description></item>
394414
/// </list>
395415
/// <para>
416+
/// <b>Multipart Download Strategy:</b>
417+
/// </para>
418+
/// <para>
419+
/// The <see cref="BaseDownloadRequest.MultipartDownloadType"/> property controls how parts are downloaded (default: <c>MultipartDownloadType.PART</c>):
420+
/// </para>
421+
/// <list type="bullet">
422+
/// <item><description><b>PART (default)</b>: Uses the original part boundaries from when the object was uploaded with multipart upload.
423+
/// This is more efficient as it aligns with S3's internal part structure, but <b>requires that the object was uploaded using multipart upload</b>.
424+
/// The <see cref="BaseDownloadRequest.PartSize"/> property is ignored in this mode.</description></item>
425+
/// <item><description><b>RANGE</b>: Uses range-based downloads with configurable part sizes via the <see cref="BaseDownloadRequest.PartSize"/> property.
426+
/// This works with any object (whether uploaded as single-part or multipart) and provides more flexibility in controlling download part sizes.</description></item>
427+
/// </list>
428+
/// <para>
429+
/// <b>When to use PART vs RANGE:</b>
430+
/// </para>
431+
/// <list type="bullet">
432+
/// <item><description>Use <b>PART</b> mode (default) when you know the object was uploaded using multipart upload and want optimal performance.</description></item>
433+
/// <item><description>Use <b>RANGE</b> mode when the object's upload method is unknown, when you need specific part sizes, or when downloading objects that were uploaded as a single part.</description></item>
434+
/// </list>
435+
/// <para>
396436
/// <b>Configuration Options:</b>
397437
/// </para>
398438
/// <para>
@@ -418,7 +458,8 @@ public partial interface ITransferUtility : IDisposable
418458
/// BucketName = "my-bucket",
419459
/// Key = "my-key",
420460
/// FilePath = "local-file.txt",
421-
/// PartSize = 16 * 1024 * 1024 // Use 16MB parts instead of default 8MB
461+
/// PartSize = 16 * 1024 * 1024, // Use 16MB parts instead of default 8MB
462+
/// MultipartDownloadType = MultipartDownloadType.RANGE // Enable RANGE mode to use custom PartSize
422463
/// };
423464
/// var response = await transferUtility.DownloadWithResponseAsync(request);
424465
/// </code>
@@ -534,6 +575,26 @@ public partial interface ITransferUtility : IDisposable
534575
/// <item><description>Downloaded parts are buffered in memory and served to your application as you read from the stream</description></item>
535576
/// </list>
536577
/// <para>
578+
/// <b>Multipart Download Strategy:</b>
579+
/// </para>
580+
/// <para>
581+
/// The <see cref="BaseDownloadRequest.MultipartDownloadType"/> property controls how parts are downloaded (default: <c>MultipartDownloadType.PART</c>):
582+
/// </para>
583+
/// <list type="bullet">
584+
/// <item><description><b>PART (default)</b>: Uses the original part boundaries from when the object was uploaded with multipart upload.
585+
/// This is more efficient as it aligns with S3's internal part structure, but <b>requires that the object was uploaded using multipart upload</b>.
586+
/// The <see cref="BaseDownloadRequest.PartSize"/> property is ignored in this mode.</description></item>
587+
/// <item><description><b>RANGE</b>: Uses range-based downloads with configurable part sizes via the <see cref="BaseDownloadRequest.PartSize"/> property.
588+
/// This works with any object (whether uploaded as single-part or multipart) and provides more flexibility in controlling download part sizes.</description></item>
589+
/// </list>
590+
/// <para>
591+
/// <b>When to use PART vs RANGE:</b>
592+
/// </para>
593+
/// <list type="bullet">
594+
/// <item><description>Use <b>PART</b> mode (default) when you know the object was uploaded using multipart upload and want optimal performance.</description></item>
595+
/// <item><description>Use <b>RANGE</b> mode when the object's upload method is unknown, when you need specific part sizes, or when downloading objects that were uploaded as a single part.</description></item>
596+
/// </list>
597+
/// <para>
537598
/// <b>Configuration Options:</b>
538599
/// </para>
539600
/// <para>
@@ -589,6 +650,26 @@ public partial interface ITransferUtility : IDisposable
589650
/// <item><description>Downloaded parts are buffered in memory and served to your application as you read from the stream</description></item>
590651
/// </list>
591652
/// <para>
653+
/// <b>Multipart Download Strategy:</b>
654+
/// </para>
655+
/// <para>
656+
/// The <see cref="BaseDownloadRequest.MultipartDownloadType"/> property controls how parts are downloaded (default: <c>MultipartDownloadType.PART</c>):
657+
/// </para>
658+
/// <list type="bullet">
659+
/// <item><description><b>PART (default)</b>: Uses the original part boundaries from when the object was uploaded with multipart upload.
660+
/// This is more efficient as it aligns with S3's internal part structure, but <b>requires that the object was uploaded using multipart upload</b>.
661+
/// The <see cref="BaseDownloadRequest.PartSize"/> property is ignored in this mode.</description></item>
662+
/// <item><description><b>RANGE</b>: Uses range-based downloads with configurable part sizes via the <see cref="BaseDownloadRequest.PartSize"/> property.
663+
/// This works with any object (whether uploaded as single-part or multipart) and provides more flexibility in controlling download part sizes.</description></item>
664+
/// </list>
665+
/// <para>
666+
/// <b>When to use PART vs RANGE:</b>
667+
/// </para>
668+
/// <list type="bullet">
669+
/// <item><description>Use <b>PART</b> mode (default) when you know the object was uploaded using multipart upload and want optimal performance.</description></item>
670+
/// <item><description>Use <b>RANGE</b> mode when the object's upload method is unknown, when you need specific part sizes, or when downloading objects that were uploaded as a single part.</description></item>
671+
/// </list>
672+
/// <para>
592673
/// <b>Configuration Options:</b>
593674
/// </para>
594675
/// <para>
@@ -615,7 +696,8 @@ public partial interface ITransferUtility : IDisposable
615696
/// {
616697
/// BucketName = "my-bucket",
617698
/// Key = "my-key",
618-
/// PartSize = 16 * 1024 * 1024 // Use 16MB parts instead of default 8MB
699+
/// PartSize = 16 * 1024 * 1024, // Use 16MB parts instead of default 8MB
700+
/// MultipartDownloadType = MultipartDownloadType.RANGE // Enable RANGE mode to use custom PartSize
619701
/// };
620702
/// var response = await transferUtility.OpenStreamWithResponseAsync(request);
621703
/// </code>

‎sdk/src/Services/S3/Custom/Transfer/_bcl+netstandard/ITransferUtility.sync.cs‎

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -360,6 +360,26 @@ public partial interface ITransferUtility
360360
/// <item><description>Downloaded parts are buffered in memory and served to your application as you read from the stream</description></item>
361361
/// </list>
362362
/// <para>
363+
/// <b>Multipart Download Strategy:</b>
364+
/// </para>
365+
/// <para>
366+
/// The <see cref="BaseDownloadRequest.MultipartDownloadType"/> property controls how parts are downloaded (default: <c>MultipartDownloadType.PART</c>):
367+
/// </para>
368+
/// <list type="bullet">
369+
/// <item><description><b>PART (default)</b>: Uses the original part boundaries from when the object was uploaded with multipart upload.
370+
/// This is more efficient as it aligns with S3's internal part structure, but <b>requires that the object was uploaded using multipart upload</b>.
371+
/// The <see cref="BaseDownloadRequest.PartSize"/> property is ignored in this mode.</description></item>
372+
/// <item><description><b>RANGE</b>: Uses range-based downloads with configurable part sizes via the <see cref="BaseDownloadRequest.PartSize"/> property.
373+
/// This works with any object (whether uploaded as single-part or multipart) and provides more flexibility in controlling download part sizes.</description></item>
374+
/// </list>
375+
/// <para>
376+
/// <b>When to use PART vs RANGE:</b>
377+
/// </para>
378+
/// <list type="bullet">
379+
/// <item><description>Use <b>PART</b> mode (default) when you know the object was uploaded using multipart upload and want optimal performance.</description></item>
380+
/// <item><description>Use <b>RANGE</b> mode when the object's upload method is unknown, when you need specific part sizes, or when downloading objects that were uploaded as a single part.</description></item>
381+
/// </list>
382+
/// <para>
363383
/// <b>Configuration Options:</b>
364384
/// </para>
365385
/// <para>
@@ -414,6 +434,26 @@ public partial interface ITransferUtility
414434
/// <item><description>Downloaded parts are buffered in memory and served to your application as you read from the stream</description></item>
415435
/// </list>
416436
/// <para>
437+
/// <b>Multipart Download Strategy:</b>
438+
/// </para>
439+
/// <para>
440+
/// The <see cref="BaseDownloadRequest.MultipartDownloadType"/> property controls how parts are downloaded (default: <c>MultipartDownloadType.PART</c>):
441+
/// </para>
442+
/// <list type="bullet">
443+
/// <item><description><b>PART (default)</b>: Uses the original part boundaries from when the object was uploaded with multipart upload.
444+
/// This is more efficient as it aligns with S3's internal part structure, but <b>requires that the object was uploaded using multipart upload</b>.
445+
/// The <see cref="BaseDownloadRequest.PartSize"/> property is ignored in this mode.</description></item>
446+
/// <item><description><b>RANGE</b>: Uses range-based downloads with configurable part sizes via the <see cref="BaseDownloadRequest.PartSize"/> property.
447+
/// This works with any object (whether uploaded as single-part or multipart) and provides more flexibility in controlling download part sizes.</description></item>
448+
/// </list>
449+
/// <para>
450+
/// <b>When to use PART vs RANGE:</b>
451+
/// </para>
452+
/// <list type="bullet">
453+
/// <item><description>Use <b>PART</b> mode (default) when you know the object was uploaded using multipart upload and want optimal performance.</description></item>
454+
/// <item><description>Use <b>RANGE</b> mode when the object's upload method is unknown, when you need specific part sizes, or when downloading objects that were uploaded as a single part.</description></item>
455+
/// </list>
456+
/// <para>
417457
/// <b>Configuration Options:</b>
418458
/// </para>
419459
/// <para>
@@ -440,7 +480,8 @@ public partial interface ITransferUtility
440480
/// {
441481
/// BucketName = "my-bucket",
442482
/// Key = "my-key",
443-
/// PartSize = 16 * 1024 * 1024 // Use 16MB parts instead of default 8MB
483+
/// PartSize = 16 * 1024 * 1024, // Use 16MB parts instead of default 8MB
484+
/// MultipartDownloadType = MultipartDownloadType.RANGE // Enable RANGE mode to use custom PartSize
444485
/// };
445486
/// var response = transferUtility.OpenStreamWithResponse(request);
446487
/// </code>
@@ -516,6 +557,26 @@ public partial interface ITransferUtility
516557
/// <item><description>Downloaded parts are written directly to the file as they arrive</description></item>
517558
/// </list>
518559
/// <para>
560+
/// <b>Multipart Download Strategy:</b>
561+
/// </para>
562+
/// <para>
563+
/// The <see cref="BaseDownloadRequest.MultipartDownloadType"/> property controls how parts are downloaded (default: <c>MultipartDownloadType.PART</c>):
564+
/// </para>
565+
/// <list type="bullet">
566+
/// <item><description><b>PART (default)</b>: Uses the original part boundaries from when the object was uploaded with multipart upload.
567+
/// This is more efficient as it aligns with S3's internal part structure, but <b>requires that the object was uploaded using multipart upload</b>.
568+
/// The <see cref="BaseDownloadRequest.PartSize"/> property is ignored in this mode.</description></item>
569+
/// <item><description><b>RANGE</b>: Uses range-based downloads with configurable part sizes via the <see cref="BaseDownloadRequest.PartSize"/> property.
570+
/// This works with any object (whether uploaded as single-part or multipart) and provides more flexibility in controlling download part sizes.</description></item>
571+
/// </list>
572+
/// <para>
573+
/// <b>When to use PART vs RANGE:</b>
574+
/// </para>
575+
/// <list type="bullet">
576+
/// <item><description>Use <b>PART</b> mode (default) when you know the object was uploaded using multipart upload and want optimal performance.</description></item>
577+
/// <item><description>Use <b>RANGE</b> mode when the object's upload method is unknown, when you need specific part sizes, or when downloading objects that were uploaded as a single part.</description></item>
578+
/// </list>
579+
/// <para>
519580
/// <b>Configuration Options:</b>
520581
/// </para>
521582
/// <para>
@@ -563,6 +624,26 @@ public partial interface ITransferUtility
563624
/// <item><description>Downloaded parts are written directly to the file as they arrive</description></item>
564625
/// </list>
565626
/// <para>
627+
/// <b>Multipart Download Strategy:</b>
628+
/// </para>
629+
/// <para>
630+
/// The <see cref="BaseDownloadRequest.MultipartDownloadType"/> property controls how parts are downloaded (default: <c>MultipartDownloadType.PART</c>):
631+
/// </para>
632+
/// <list type="bullet">
633+
/// <item><description><b>PART (default)</b>: Uses the original part boundaries from when the object was uploaded with multipart upload.
634+
/// This is more efficient as it aligns with S3's internal part structure, but <b>requires that the object was uploaded using multipart upload</b>.
635+
/// The <see cref="BaseDownloadRequest.PartSize"/> property is ignored in this mode.</description></item>
636+
/// <item><description><b>RANGE</b>: Uses range-based downloads with configurable part sizes via the <see cref="BaseDownloadRequest.PartSize"/> property.
637+
/// This works with any object (whether uploaded as single-part or multipart) and provides more flexibility in controlling download part sizes.</description></item>
638+
/// </list>
639+
/// <para>
640+
/// <b>When to use PART vs RANGE:</b>
641+
/// </para>
642+
/// <list type="bullet">
643+
/// <item><description>Use <b>PART</b> mode (default) when you know the object was uploaded using multipart upload and want optimal performance.</description></item>
644+
/// <item><description>Use <b>RANGE</b> mode when the object's upload method is unknown, when you need specific part sizes, or when downloading objects that were uploaded as a single part.</description></item>
645+
/// </list>
646+
/// <para>
566647
/// <b>Configuration Options:</b>
567648
/// </para>
568649
/// <para>
@@ -588,7 +669,8 @@ public partial interface ITransferUtility
588669
/// BucketName = "my-bucket",
589670
/// Key = "my-key",
590671
/// FilePath = "local-file.txt",
591-
/// PartSize = 16 * 1024 * 1024 // Use 16MB parts instead of default 8MB
672+
/// PartSize = 16 * 1024 * 1024, // Use 16MB parts instead of default 8MB
673+
/// MultipartDownloadType = MultipartDownloadType.RANGE // Enable RANGE mode to use custom PartSize
592674
/// };
593675
/// var response = transferUtility.DownloadWithResponse(request);
594676
/// </code>

0 commit comments

Comments
 (0)