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

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

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

📋 Pull Request Information

Original PR: https://github.com/adamhathcock/sharpcompress/pull/1080
Author: @Copilot
Created: 12/19/2025
Status: ✅ Merged
Merged: 12/19/2025
Merged by: @adamhathcock

Base: master ← Head: copilot/refactor-write-to-directory-consistency

📝 Commits (9)

  • 3f9986c Initial plan
  • 8b95e0a Standardize on WriteToDirectory naming and add async support
  • 0e59bf3 Add test for IArchive.WriteToDirectoryAsync
  • 54b64a8 Fix misleading variable name: emptyDirectory -> parentDirectory
  • 17bde8d Merge branch 'master' of https://github.com/adamhathcock/sharpcompress into copilot/refactor-write-to-directory-consistency
  • 2f0eb0b Replace Action with IProgress for progress reporting
  • c701bbb Run CSharpier formatting and document check-format process
  • d392991 Remove CancellationToken from synchronous WriteToDirectory overload
  • c2e0179 refactor archive extensions

📊 Changes

4 files changed (+200 additions, -61 deletions)

View changed files

📝 AGENTS.md (+26 -4)
📝 src/SharpCompress/Archives/IArchiveExtensions.cs (+139 -56)
📝 tests/SharpCompress.Test/ArchiveTests.cs (+1 -1)
📝 tests/SharpCompress.Test/Zip/ZipArchiveAsyncTests.cs (+34 -0)

📄 Description

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.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/adamhathcock/sharpcompress/pull/1080 **Author:** [@Copilot](https://github.com/apps/copilot-swe-agent) **Created:** 12/19/2025 **Status:** ✅ Merged **Merged:** 12/19/2025 **Merged by:** [@adamhathcock](https://github.com/adamhathcock) **Base:** `master` ← **Head:** `copilot/refactor-write-to-directory-consistency` --- ### 📝 Commits (9) - [`3f9986c`](https://github.com/adamhathcock/sharpcompress/commit/3f9986c13c973f5e9b8e08da8bfb5e8259044a44) Initial plan - [`8b95e0a`](https://github.com/adamhathcock/sharpcompress/commit/8b95e0a76d6b387533175730e2895ccd16772d07) Standardize on WriteToDirectory naming and add async support - [`0e59bf3`](https://github.com/adamhathcock/sharpcompress/commit/0e59bf39f4bb77859416bad08c84bf8ff351b962) Add test for IArchive.WriteToDirectoryAsync - [`54b64a8`](https://github.com/adamhathcock/sharpcompress/commit/54b64a8c3b7956f745bea7b14eb76dd0b9934430) Fix misleading variable name: emptyDirectory -> parentDirectory - [`17bde8d`](https://github.com/adamhathcock/sharpcompress/commit/17bde8da8a5fb59637eead10b034ff79199351d6) Merge branch 'master' of https://github.com/adamhathcock/sharpcompress into copilot/refactor-write-to-directory-consistency - [`2f0eb0b`](https://github.com/adamhathcock/sharpcompress/commit/2f0eb0bd4b733929397c68881ae21904ff42a0d6) Replace Action<double> with IProgress<ProgressReport> for progress reporting - [`c701bbb`](https://github.com/adamhathcock/sharpcompress/commit/c701bbbee3697693bfcf76f81b543df19c14c848) Run CSharpier formatting and document check-format process - [`d392991`](https://github.com/adamhathcock/sharpcompress/commit/d39299176476a3fd230bb4b9ed1dc51e95e2be7d) Remove CancellationToken from synchronous WriteToDirectory overload - [`c2e0179`](https://github.com/adamhathcock/sharpcompress/commit/c2e01798f8bbe63fd4c3568d8e2d594d7c504ae9) refactor archive extensions ### 📊 Changes **4 files changed** (+200 additions, -61 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+26 -4) 📝 `src/SharpCompress/Archives/IArchiveExtensions.cs` (+139 -56) 📝 `tests/SharpCompress.Test/ArchiveTests.cs` (+1 -1) 📝 `tests/SharpCompress.Test/Zip/ZipArchiveAsyncTests.cs` (+34 -0) </details> ### 📄 Description ## 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). --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
claunia added the pull-request label 2026-01-29 22:20:53 +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#1504
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?