BizzelTech.FileZip 1.0.0

BizzelTech.FileZip

A comprehensive .NET library for zipping and unzipping files and folders with password protection support. This library provides easy-to-use APIs for creating, extracting, and managing password-protected zip archives.

Features

• ✅ Password Protection - Create and extract password-protected zip files
• ✅ Multiple Compression Levels - Choose from optimal, fastest, or no compression
• ✅ Fluent API - Easy-to-use fluent interface for common operations
• ✅ File and Directory Support - Zip individual files, entire directories, or mixed collections
• ✅ Pattern Matching - Include/exclude files based on patterns (*.txt, *.log, etc.)
• ✅ Timestamp Preservation - Maintain original file timestamps
• ✅ Directory Structure Control - Choose to preserve or flatten directory structures
• ✅ Progress Tracking - Detailed results with compression ratios and processing times
• ✅ Cross-Platform - Supports .NET 8, 9, and 10
• ✅ Logging Support - Optional Microsoft.Extensions.Logging integration

Installation

dotnet add package BizzelTech.FileZip

Quick Start

Simple File Operations

using BizzelTech.FileZip;

// Zip a single file
var result = await FileZip.ZipFileAsync("document.txt", "archive.zip");

// Zip a single file with password
var result = await FileZip.ZipFileAsync("document.txt", "archive.zip", "mypassword");

// Zip a directory
var result = await FileZip.ZipDirectoryAsync("MyFolder", "folder-archive.zip");

// Unzip a file
var result = await FileZip.UnzipAsync("archive.zip", "extracted-files");

// Unzip a password-protected file
var result = await FileZip.UnzipAsync("archive.zip", "extracted-files", "mypassword");

Fluent API

using BizzelTech.FileZip;
using System.IO.Compression;

// Create a zip with multiple files and directories
var result = await FileZip.Create()
    .AddFile("document1.txt")
    .AddFile("document2.pdf")
    .AddDirectory("MyFolder")
    .WithPassword("secretpassword")
    .WithCompressionLevel(CompressionLevel.Optimal)
    .ExcludePatterns("*.tmp", "*.log")
    .To("comprehensive-archive.zip")
    .ZipAsync();

// Extract with specific options
var extractResult = await FileZip.Create()
    .AddFile("archive.zip")
    .WithPassword("secretpassword")
    .IncludePatterns("*.pdf", "*.docx")
    .OverwriteDestination(false)
    .PreserveDirectoryStructure(true)
    .To("extracted-documents")
    .UnzipAsync();

Advanced Usage

Working with ZipService Directly

using BizzelTech.FileZip.Services;
using BizzelTech.FileZip.Models;
using Microsoft.Extensions.Logging;

// Create service with logging
var logger = LoggerFactory.Create(builder => builder.AddConsole())
    .CreateLogger<ZipService>();
var zipService = new ZipService(logger);

// Configure compression options
var options = new ZipOptions
{
    Password = "mypassword",
    CompressionLevel = CompressionLevel.Optimal,
    IncludeRootDirectory = false,
    ExcludePatterns = new[] { "*.tmp", "*.bak", "node_modules" },
    PreserveTimestamps = true
};

// Zip multiple sources
var sources = new[] { "file1.txt", "file2.pdf", "MyFolder" };
var result = await zipService.ZipMultipleAsync(sources, "multi-source.zip", options);

if (result.Success)
{
    Console.WriteLine($"Compressed {result.FilesCompressed} files");
    Console.WriteLine($"Original size: {result.UncompressedSize:N0} bytes");
    Console.WriteLine($"Compressed size: {result.CompressedSize:N0} bytes");
    Console.WriteLine($"Compression ratio: {result.CompressionRatio:F1}%");
    Console.WriteLine($"Time taken: {result.Duration.TotalSeconds:F2} seconds");
}

Extraction with Custom Options

var extractOptions = new UnzipOptions
{
    Password = "mypassword",
    OverwriteFiles = true,
    CreateDestinationDirectory = true,
    IncludePatterns = new[] { "*.pdf", "*.docx", "*.xlsx" },
    ExcludePatterns = new[] { "*.tmp" },
    PreserveTimestamps = true,
    PreserveDirectoryStructure = true
};

var result = await zipService.UnzipAsync("archive.zip", "extracted", extractOptions);

Listing Zip Contents

// List all files in a zip archive
var entries = await zipService.ListZipContentsAsync("archive.zip", "password");

foreach (var entry in entries)
{
    Console.WriteLine($"{entry.Name} - {entry.Size} bytes - {entry.DateTime}");
}

Configuration Options

ZipOptions

UnzipOptions

Pattern Matching

The library supports simple wildcard patterns for including and excluding files:

// Exclude temporary and log files
.ExcludePatterns("*.tmp", "*.log", "*.bak")

// Include only specific document types
.IncludePatterns("*.pdf", "*.docx", "*.xlsx")

// Exclude entire directories by name
.ExcludePatterns("node_modules", "bin", "obj")

Result Objects

ZipResult

public class ZipResult
{
    public bool Success { get; set; }
    public string? ErrorMessage { get; set; }
    public string? ZipFilePath { get; set; }
    public int FilesCompressed { get; set; }
    public long UncompressedSize { get; set; }
    public long CompressedSize { get; set; }
    public double CompressionRatio { get; } // Calculated property
    public TimeSpan Duration { get; set; }
    public IList<string> ProcessedFiles { get; set; }
}

UnzipResult

public class UnzipResult
{
    public bool Success { get; set; }
    public string? ErrorMessage { get; set; }
    public string? ExtractionPath { get; set; }
    public int FilesExtracted { get; set; }
    public long ExtractedSize { get; set; }
    public TimeSpan Duration { get; set; }
    public IList<string> ExtractedFiles { get; set; }
}

Error Handling

var result = await FileZip.ZipDirectoryAsync("NonExistentFolder", "output.zip");

if (!result.Success)
{
    Console.WriteLine($"Zip operation failed: {result.ErrorMessage}");
    return;
}

Console.WriteLine($"Successfully created {result.ZipFilePath}");

Dependency Injection

// In your startup/configuration
services.AddSingleton<ZipService>();

// In your service/controller
public class DocumentService
{
    private readonly ZipService _zipService;
    
    public DocumentService(ZipService zipService)
    {
        _zipService = zipService;
    }
    
    public async Task<ZipResult> ArchiveDocuments(IEnumerable<string> filePaths)
    {
        var options = ZipOptions.WithPassword("secure123");
        return await _zipService.ZipMultipleAsync(filePaths, "documents.zip", options);
    }
}

Performance Considerations

• Use CompressionLevel.Fastest for large files when speed is more important than size
• Use CompressionLevel.NoCompression for already compressed files (images, videos)
• Enable logging to monitor performance and troubleshoot issues
• Consider excluding unnecessary files using pattern matching to improve performance

Compatibility

• .NET 8.0 and later
• .NET 9.0 and later
• .NET 10.0 and later

Dependencies

• SharpZipLib - For advanced zip operations and password protection
• Microsoft.Extensions.Logging.Abstractions - For optional logging support

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and feature requests, please use the GitHub Issues page.