starred/sharpcompress
1
0
Fork 0
mirror of https://github.com/adamhathcock/sharpcompress.git synced 2026-02-03 21:23:38 +00:00
Code Issues 975 Packages Projects Releases 20 Wiki Activity

[PR #1080] Standardize extraction API to WriteToDirectory with IProgress support #1508

New Issue
Closed
opened 2026-01-29 22:20:54 +00:00 by claunia · 0 comments
claunia commented 2026-01-29 22:20:54 +00:00
Owner
Copy Link

Original Pull Request: https://github.com/adamhathcock/sharpcompress/pull/1080

State: closed
Merged: Yes

Standardize on WriteToDirectory Naming

This PR resolves the naming inconsistency between WriteToDirectory and ExtractToDirectory methods as requested in the issue.

Changes Made

1. ✅ Removed ExtractToDirectory method

  • Deleted from IArchiveExtensions.cs to standardize on WriteToDirectory naming

2. ✅ Enhanced WriteToDirectory overloads

  • Basic overload: Now intelligently handles both solid and non-solid archives:
    • Solid archives (Rar, 7Zip): Uses ExtractAllEntries() for optimal performance
    • Non-solid archives: Directly iterates entries
  • Progress overload: Uses IProgress<ProgressReport> for consistent progress reporting (without CancellationToken for sync methods)

3. ✅ Added WriteToDirectoryAsync

  • New async method for IArchive with full async/await support
  • Supports ExtractionOptions, IProgress<ProgressReport> progress reporting, and cancellation tokens
  • Follows existing async patterns in the codebase

4. ✅ Updated Tests

  • Modified ArchiveExtractToDirectory test helper to use WriteToDirectory
  • Added comprehensive test for new WriteToDirectoryAsync method
  • Added test for progress reporting with IProgress<ProgressReport>
  • All tests passing (481+ tests across all archive types)

5. ✅ Code Quality

  • Renamed misleading variable emptyDirectory to parentDirectory
  • Added proper XML documentation for all methods
  • Follows existing code conventions and patterns

6. ✅ Merged master branch

  • Successfully merged latest master branch
  • No merge conflicts
  • All tests still passing after merge

7. ✅ Standardized on IProgress

  • Replaced Action<double> with IProgress<ProgressReport> for consistency with the rest of the codebase
  • Progress reports now include entry path, bytes transferred, and total bytes
  • More informative progress reporting aligned with existing patterns

8. ✅ Code Formatting

  • Ran CSharpier formatting to ensure consistent code style
  • Documented check-format process in AGENTS.md with clear commands
  • Added instructions for dotnet csharpier check . and dotnet csharpier format .

9. ✅ Removed CancellationToken from sync method

  • Removed CancellationToken parameter from synchronous WriteToDirectory(string, ExtractionOptions?, IProgress<ProgressReport>?)
  • Cancellation tokens are for async operations; sync methods don't need them
  • Keeps API clean and consistent with standard .NET patterns

API Consistency Verification

All archive and reader types now have consistent WriteTo* naming patterns:

IArchive (IArchiveExtensions):

  • WriteToDirectory(string, ExtractionOptions?)
  • WriteToDirectory(string, ExtractionOptions?, IProgress?)
  • WriteToDirectoryAsync(string, ExtractionOptions?, IProgress?, CancellationToken)

IArchiveEntry (IArchiveEntryExtensions):

  • WriteTo, WriteToAsync, WriteToDirectory, WriteToDirectoryAsync, WriteToFile, WriteToFileAsync

IReader (IReaderExtensions):

  • WriteEntryTo, WriteAllToDirectory, WriteAllToDirectoryAsync, WriteEntryToDirectory, WriteEntryToDirectoryAsync, WriteEntryToFile, WriteEntryToFileAsync

ArchiveFactory (static):

  • WriteToDirectory(string, string, ExtractionOptions?)

Breaking Change Notice

⚠️ Breaking Change: ExtractToDirectory method has been removed.

Migration Guide:

// Old code:
archive.ExtractToDirectory(destination, progressCallback, cancellationToken);

// New code with IProgress (sync):
var progress = new Progress<ProgressReport>(report => 
{
    Console.WriteLine($"Progress: {report.PercentComplete:F2}%");
});
archive.WriteToDirectory(destination, options: null, progress);

// Or async (with cancellation):
await archive.WriteToDirectoryAsync(destination, options: null, progress, cancellationToken);

Test Results

  • ✅ 129 Zip archive tests passed
  • ✅ 35 Zip async tests passed (including new progress test)
  • ✅ 221 general archive tests passed
  • ✅ 119 Rar archive tests passed
  • ✅ 17 Tar archive tests passed
  • ✅ CSharpier formatting check passes

Files Modified

  • src/SharpCompress/Archives/IArchiveExtensions.cs - Main API changes with IProgress and formatting
  • tests/SharpCompress.Test/ArchiveTests.cs - Test helper update
  • tests/SharpCompress.Test/Zip/ZipArchiveAsyncTests.cs - New async tests with progress
  • AGENTS.md - Added detailed documentation for check-format process
Original prompt

This section details on the original issue you should resolve

<issue_title>WriteToDirectory v ExtractToDirectory consistency</issue_title>
<issue_description>The static method WriteToDirectory now internally calls ExtractToDirectory, which creates a naming inconsistency. Consider either renaming the public method to ExtractToDirectory for consistency, or documenting why WriteToDirectory internally uses ExtractToDirectory to help future maintainers understand the design choice.

I like WriteToDirectory (and async variants) but unsure of ExtractToDirectory.

ExtractToDirectory should probably be removed in favor of things named WriteToDirectory.

All archive and reader types need to have WriteTo options via itself or a parent class</issue_description>

Comments on the Issue (you are @copilot in this section)

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

**Original Pull Request:** https://github.com/adamhathcock/sharpcompress/pull/1080 **State:** closed **Merged:** Yes --- ## Standardize on WriteToDirectory Naming This PR resolves the naming inconsistency between `WriteToDirectory` and `ExtractToDirectory` methods as requested in the issue. ### Changes Made #### 1. ✅ Removed `ExtractToDirectory` method - Deleted from `IArchiveExtensions.cs` to standardize on `WriteToDirectory` naming #### 2. ✅ Enhanced `WriteToDirectory` overloads - **Basic overload**: Now intelligently handles both solid and non-solid archives: - Solid archives (Rar, 7Zip): Uses `ExtractAllEntries()` for optimal performance - Non-solid archives: Directly iterates entries - **Progress overload**: Uses `IProgress<ProgressReport>` for consistent progress reporting (without CancellationToken for sync methods) #### 3. ✅ Added `WriteToDirectoryAsync` - New async method for `IArchive` with full async/await support - Supports ExtractionOptions, `IProgress<ProgressReport>` progress reporting, and cancellation tokens - Follows existing async patterns in the codebase #### 4. ✅ Updated Tests - Modified `ArchiveExtractToDirectory` test helper to use `WriteToDirectory` - Added comprehensive test for new `WriteToDirectoryAsync` method - Added test for progress reporting with `IProgress<ProgressReport>` - All tests passing (481+ tests across all archive types) #### 5. ✅ Code Quality - Renamed misleading variable `emptyDirectory` to `parentDirectory` - Added proper XML documentation for all methods - Follows existing code conventions and patterns #### 6. ✅ Merged master branch - Successfully merged latest master branch - No merge conflicts - All tests still passing after merge #### 7. ✅ Standardized on IProgress<ProgressReport> - Replaced `Action<double>` with `IProgress<ProgressReport>` for consistency with the rest of the codebase - Progress reports now include entry path, bytes transferred, and total bytes - More informative progress reporting aligned with existing patterns #### 8. ✅ Code Formatting - Ran CSharpier formatting to ensure consistent code style - Documented check-format process in AGENTS.md with clear commands - Added instructions for `dotnet csharpier check .` and `dotnet csharpier format .` #### 9. ✅ Removed CancellationToken from sync method - Removed `CancellationToken` parameter from synchronous `WriteToDirectory(string, ExtractionOptions?, IProgress<ProgressReport>?)` - Cancellation tokens are for async operations; sync methods don't need them - Keeps API clean and consistent with standard .NET patterns ### API Consistency Verification All archive and reader types now have consistent `WriteTo*` naming patterns: **IArchive** (IArchiveExtensions): - WriteToDirectory(string, ExtractionOptions?) - WriteToDirectory(string, ExtractionOptions?, IProgress<ProgressReport>?) - WriteToDirectoryAsync(string, ExtractionOptions?, IProgress<ProgressReport>?, CancellationToken) **IArchiveEntry** (IArchiveEntryExtensions): - WriteTo, WriteToAsync, WriteToDirectory, WriteToDirectoryAsync, WriteToFile, WriteToFileAsync **IReader** (IReaderExtensions): - WriteEntryTo, WriteAllToDirectory, WriteAllToDirectoryAsync, WriteEntryToDirectory, WriteEntryToDirectoryAsync, WriteEntryToFile, WriteEntryToFileAsync **ArchiveFactory** (static): - WriteToDirectory(string, string, ExtractionOptions?) ### Breaking Change Notice ⚠️ **Breaking Change**: `ExtractToDirectory` method has been removed. **Migration Guide**: ```csharp // Old code: archive.ExtractToDirectory(destination, progressCallback, cancellationToken); // New code with IProgress (sync): var progress = new Progress<ProgressReport>(report => { Console.WriteLine($"Progress: {report.PercentComplete:F2}%"); }); archive.WriteToDirectory(destination, options: null, progress); // Or async (with cancellation): await archive.WriteToDirectoryAsync(destination, options: null, progress, cancellationToken); ``` ### Test Results - ✅ 129 Zip archive tests passed - ✅ 35 Zip async tests passed (including new progress test) - ✅ 221 general archive tests passed - ✅ 119 Rar archive tests passed - ✅ 17 Tar archive tests passed - ✅ CSharpier formatting check passes ### Files Modified - `src/SharpCompress/Archives/IArchiveExtensions.cs` - Main API changes with IProgress and formatting - `tests/SharpCompress.Test/ArchiveTests.cs` - Test helper update - `tests/SharpCompress.Test/Zip/ZipArchiveAsyncTests.cs` - New async tests with progress - `AGENTS.md` - Added detailed documentation for check-format process <!-- START COPILOT ORIGINAL PROMPT --> <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>WriteToDirectory v ExtractToDirectory consistency</issue_title> > <issue_description>The static method WriteToDirectory now internally calls ExtractToDirectory, which creates a naming inconsistency. Consider either renaming the public method to ExtractToDirectory for consistency, or documenting why WriteToDirectory internally uses ExtractToDirectory to help future maintainers understand the design choice. > > I like WriteToDirectory (and async variants) but unsure of ExtractToDirectory. > > ExtractToDirectory should probably be removed in favor of things named WriteToDirectory. > > All archive and reader types need to have WriteTo options via itself or a parent class</issue_description> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details> <!-- START COPILOT CODING AGENT SUFFIX --> - Fixes adamhathcock/sharpcompress#1079 <!-- START COPILOT CODING AGENT TIPS --> --- 💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).
claunia added the pull-request label 2026-01-29 22:20:54 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
duplicate
enhancement
feedback requested
not bug
pull-request
Mirrored from GitHub Pull Request
 question
up for grabs
wontfix
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
claunia
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/sharpcompress#1508
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?