Getting Started with SharpArchiver: Installation, Tips, and Best Practices

Getting Started with SharpArchiver: Installation, Tips, and Best PracticesSharpArchiver is a modern, high-performance .NET library for creating, extracting, and managing archive files (ZIP, TAR, and more). It aims to be simple for beginners while providing advanced features for production use: streaming support, strong encryption, multi-threading, and fine-grained control over compression settings. This guide will walk you through installation, core concepts, common usage patterns, tips for performance and reliability, and best practices for production deployments.

---

What SharpArchiver is and when to use it

SharpArchiver is designed for developers building applications that need reliable archive handling: backup tools, deployment systems, file managers, content delivery pipelines, and server-side batch processing. Use SharpArchiver when you need:

• Programmatic creation and extraction of archives (ZIP, TAR, etc.)
• Streaming operations that avoid loading whole files into memory
• Customizable compression levels and formats
• Encryption and integrity checks for secure archives
• High throughput via multi-threaded compression/decompression

---

Installing SharpArchiver

SharpArchiver is available as a NuGet package. To install, run one of the following commands in your project directory or use the Package Manager in Visual Studio:

• .NET CLI:

  dotnet add package SharpArchiver 

• NuGet Package Manager:

  Install-Package SharpArchiver 

Make sure your project targets a supported .NET version (check the package page for current compatibility). After installation, add the appropriate using statement to your code files:

using SharpArchiver; using SharpArchiver.Format; using SharpArchiver.Streams; 

---

Basic usage: creating and extracting archives

Below are common patterns you’ll use frequently.

Creating a ZIP archive from files:

using (var archive = new ZipArchive("backup.zip", ArchiveMode.Create)) {     archive.AddFile("docs/report.pdf", "reports/report.pdf");     archive.AddFile("images/logo.png", "assets/logo.png");     archive.Save(); } 

Extracting a ZIP archive:

using (var archive = ZipArchive.Open("backup.zip")) {     foreach (var entry in archive.Entries)     {         entry.ExtractToDirectory("output");     } } 

Streaming file into an archive (no full-file buffering):

using var input = File.OpenRead("large-video.mp4"); using var archive = new ZipArchive("streamed.zip", ArchiveMode.Create); archive.AddEntry("videos/large-video.mp4", input); archive.Save(); 

Creating a TAR.GZ archive:

using var tarGz = new TarGzArchive("package.tar.gz", ArchiveMode.Create); tarGz.AddDirectory("build/output", "app"); tarGz.Save(); 

---

Important concepts and API surface

• Archive formats: ZIP, TAR, TAR.GZ, TAR.BZ2 (availability depends on build)
• Archive modes: Create, Read, Update (where supported)
• Entries: files and directories inside archives; support for metadata like timestamps, permissions, and ownership (useful for TAR)
• Streams: supports adding entries from Streams to avoid buffering large files in memory
• Compression: per-entry compression level and algorithm selection
• Encryption: password protection and AES encryption options for ZIP entries
• Events and hooks: progress callbacks, cancellation tokens, and custom entry processors

---

Tips for performance and resource usage

• Prefer streaming APIs (AddEntry with Stream) for large files to avoid OOM.
• Use appropriate compression level: store (no compression) for already-compressed media; fast for speed-sensitive operations; optimal for smallest size.
• Enable parallel compression if available and your workload is CPU-bound and I/O is not the bottleneck. Example:

  
  var options = new ArchiveOptions { ParallelCompression = true, MaxDegreeOfParallelism = Environment.ProcessorCount }; using var archive = new ZipArchive("out.zip", ArchiveMode.Create, options); 

• Batch small files into a temporary tar stream before compressing to reduce per-entry overhead for ZIP.
• For network operations, upload archives as streams directly to the network client instead of writing to disk first.

---

Reliability and error handling

• Always use using statements or try/finally to ensure streams and archives are closed.
• Validate entries before adding: ensure no path traversal (../) or absolute paths unless intentionally allowed. Sanitize entry names:

  
  string SafeEntryName(string path) { var entry = path.Replace('\', '/').TrimStart('/'); return entry.Contains("..") ? throw new InvalidOperationException("Invalid path") : entry; } 

• Use checksums (CRC or SHA-256) for critical archives to detect corruption. SharpArchiver can compute checksums per entry; store them alongside archives or in metadata.
• Respect file locks and permissions: catch UnauthorizedAccessException and handle accordingly.

---

Security considerations

• When extracting archives from untrusted sources, never extract blindly — validate entry paths to avoid zip-slip attacks. Always restrict extraction to a safe base directory.
• Prefer AES encryption when protecting sensitive content. Remember that passwords must be handled securely (use secure string and key derivation).
• Avoid using default or empty passwords. Rotate keys/passwords for long-lived archives.
• Be cautious with symbolic links inside archives — they can be used to overwrite files outside the extraction directory on some platforms.

---

Integration examples

Continuous integration: create build artifacts as compressed archives and upload to artifact storage. Example using a CI script:

dotnet publish -c Release -o out dotnet run --project Tools/Packager -- out packaged.zip # upload packaged.zip to storage 

Web streaming: create an archive on-the-fly and stream to HTTP response to save disk space:

app.MapGet("/download/{id}", async (HttpContext ctx, string id) => {     ctx.Response.ContentType = "application/zip";     using var archive = new ZipArchive(Stream.Null /*replace with ctx.Response.Body*/, ArchiveMode.Create);     // add entries from storage streams     await archive.SaveAsync(ctx.RequestAborted); }); 

---

Troubleshooting common issues

• “Out of memory” — switch to stream-based APIs and lower concurrency.
• Slow compression — lower compression level or use faster algorithm; ensure I/O isn’t the bottleneck.
• Corrupted archive errors — verify CRC/checksums, ensure archive stream is fully flushed/closed before use.

---

Best practices checklist

• Use streaming for large files.
• Sanitize entry names and guard against zip-slip.
• Choose compression level based on file types.
• Encrypt sensitive archives with strong algorithms.
• Close archives and streams promptly.
• Use checksums for integrity verification.
• Test extraction on target platforms, especially for TAR and permissions.
• Document archive format choices for downstream consumers.

---

SharpArchiver provides a balance of simplicity and power for .NET developers handling archives. Start with the basic examples above, then adopt streaming, error handling, and security practices as your needs grow.