Bastion Archive Sdk

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Threading
Imports System.Threading.Tasks
Imports Bastion.Archive
Imports Bastion.Archive.Diagnostics

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Await the library: write an archive to a stream that refuses synchronous writes, open one from a stream that
    ''' cannot seek, and cancel an extraction — which gives a result, not an exception.
    ''' </summary>
    ''' <remarks>
    ''' ASP.NET Core's request and response bodies refuse synchronous I/O by default. <c>CreateAsync</c> writes to such
    ''' a stream through <c>WriteAsync</c> alone, and <c>OpenAsync</c> copies a stream that cannot seek to a temporary
    ''' file first, since ZIP keeps its directory at the end. Every <c>Async</c> method completes with the same result
    ''' its synchronous twin returns; a cancelled token ends it with <see cref="ErrorCode.Cancelled"/> rather than
    ''' throwing. The recipe runner is synchronous, so it waits on the task at the top; an application awaits.
    ''' </remarks>
    Friend Module AsyncAwaitRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            ' A console program has no synchronisation context, so waiting here cannot deadlock.
            Return RunAsync(context).GetAwaiter().GetResult()
        End Function

        Private Async Function RunAsync(context As RecipeContext) As Task(Of RecipeOutcome)
            Dim source = context.CreateSampleTree()

            ' 1. Write to a "response body" that throws on any synchronous write.
            Dim body As New MemoryStream()
            Dim started = Await ArchiveWriter.CreateAsync(New AsyncOnlyStream(body), Nothing, Nothing)
            If Not started.Succeeded Then Return RecipeOutcome.Failed
            Using writer = started.Writer
                If Not (Await writer.AddDirectoryAsync(source, Nothing)).Succeeded Then Return RecipeOutcome.Failed
                Dim completed = Await writer.CompleteAsync()
                If Not completed.Succeeded Then
                    context.Say(completed.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using
            context.Say("wrote {0} bytes through WriteAsync alone", body.Length)

            ' 2. Open it again from an "upload" that cannot seek and refuses synchronous reads.
            body.Position = 0
            Dim opened = Await Archive.OpenAsync(New AsyncOnlyStream(body))
            If Not opened.Succeeded Then Return RecipeOutcome.Failed
            Using archive = opened.Archive
                context.Say("opened from a stream that cannot seek: {0} entries", archive.Entries.Count)

                ' 3. Cancel before extracting: the task completes, and the result says so.
                Using cancellation As New CancellationTokenSource()
                    cancellation.Cancel()
                    Dim cancelled = Await archive.ExtractAllAsync(context.PathTo("cancelled"), Nothing, cancellation.Token)
                    context.Say("a cancelled extraction returned {0}", cancelled.ErrorCode)
                    If cancelled.ErrorCode <> ErrorCode.Cancelled Then Return RecipeOutcome.Failed
                End Using

                Dim extracted = Await archive.ExtractAllAsync(context.PathTo("unpacked"))
                context.Say("then extracted: {0}", If(extracted.Succeeded, "succeeded", extracted.ToString()))
                If Not extracted.Succeeded Then Return RecipeOutcome.Failed
            End Using
            Return If(File.Exists(Path.Combine(context.PathTo("unpacked"), "readme.txt")), RecipeOutcome.Passed, RecipeOutcome.Failed)
        End Function

        ''' <summary>A stream as ASP.NET Core's bodies are by default: no seeking, and no synchronous reads or writes.</summary>
        Private NotInheritable Class AsyncOnlyStream
            Inherits Stream

            Private ReadOnly _inner As Stream

            Public Sub New(inner As Stream)
                _inner = inner
            End Sub

            Public Overrides ReadOnly Property CanRead As Boolean
                Get
                    Return True
                End Get
            End Property

            Public Overrides ReadOnly Property CanSeek As Boolean
                Get
                    Return False
                End Get
            End Property

            Public Overrides ReadOnly Property CanWrite As Boolean
                Get
                    Return True
                End Get
            End Property

            Public Overrides ReadOnly Property Length As Long
                Get
                    Throw New NotSupportedException()
                End Get
            End Property

            Public Overrides Property Position As Long
                Get
                    Throw New NotSupportedException()
                End Get
                Set(value As Long)
                    Throw New NotSupportedException()
                End Set
            End Property

            Public Overrides Sub Flush()
                Throw New InvalidOperationException("Synchronous operations are disallowed.")
            End Sub

            Public Overrides Function FlushAsync(cancellationToken As CancellationToken) As Task
                Return Task.CompletedTask
            End Function

            Public Overrides Function Read(buffer() As Byte, offset As Integer, count As Integer) As Integer
                Throw New InvalidOperationException("Synchronous operations are disallowed.")
            End Function

            Public Overrides Function ReadAsync(buffer() As Byte, offset As Integer, count As Integer, cancellationToken As CancellationToken) As Task(Of Integer)
                Return _inner.ReadAsync(buffer, offset, count, cancellationToken)
            End Function

            Public Overrides Sub Write(buffer() As Byte, offset As Integer, count As Integer)
                Throw New InvalidOperationException("Synchronous operations are disallowed.")
            End Sub

            Public Overrides Function WriteAsync(buffer() As Byte, offset As Integer, count As Integer, cancellationToken As CancellationToken) As Task
                Return _inner.WriteAsync(buffer, offset, count, cancellationToken)
            End Function

#If NETCOREAPP2_1_OR_GREATER Then
            Public Overloads Overrides Function ReadAsync(buffer As Memory(Of Byte), Optional cancellationToken As CancellationToken = Nothing) As ValueTask(Of Integer)
                Return _inner.ReadAsync(buffer, cancellationToken)
            End Function

            Public Overloads Overrides Function WriteAsync(buffer As ReadOnlyMemory(Of Byte), Optional cancellationToken As CancellationToken = Nothing) As ValueTask
                Return _inner.WriteAsync(buffer, cancellationToken)
            End Function
#End If

            Public Overrides Function Seek(offset As Long, origin As SeekOrigin) As Long
                Throw New NotSupportedException()
            End Function

            Public Overrides Sub SetLength(value As Long)
                Throw New NotSupportedException()
            End Sub
        End Class

    End Module

End Namespace

C#

using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Await the library: write an archive to a stream that refuses synchronous writes, open one from a stream that
    /// cannot seek, and cancel an extraction — which gives a result, not an exception.
    /// </summary>
    /// <remarks>
    /// ASP.NET Core's request and response bodies refuse synchronous I/O by default. <c>CreateAsync</c> writes to such
    /// a stream through <c>WriteAsync</c> alone, and <c>OpenAsync</c> copies a stream that cannot seek to a temporary
    /// file first, since ZIP keeps its directory at the end. Every <c>Async</c> method completes with the same result
    /// its synchronous twin returns; a cancelled token ends it with <see cref="ErrorCode.Cancelled"/> rather than
    /// throwing. The recipe runner is synchronous, so it waits on the task at the top; an application awaits.
    /// </remarks>
    internal static class AsyncAwaitRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            // A console program has no synchronisation context, so waiting here cannot deadlock.
            return RunAsync(context).GetAwaiter().GetResult();
        }

        private static async Task<RecipeOutcome> RunAsync(RecipeContext context)
        {
            var source = context.CreateSampleTree();

            // 1. Write to a "response body" that throws on any synchronous write.
            var body = new MemoryStream();
            var started = await ArchiveWriter.CreateAsync(new AsyncOnlyStream(body), null, null);
            if (!started.Succeeded) return RecipeOutcome.Failed;
            using (var writer = started.Writer)
            {
                if (!(await writer.AddDirectoryAsync(source, null)).Succeeded) return RecipeOutcome.Failed;
                var completed = await writer.CompleteAsync();
                if (!completed.Succeeded)
                {
                    context.Say(completed.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            context.Say("wrote {0} bytes through WriteAsync alone", body.Length);

            // 2. Open it again from an "upload" that cannot seek and refuses synchronous reads.
            body.Position = 0;
            var opened = await Archive.OpenAsync(new AsyncOnlyStream(body));
            if (!opened.Succeeded) return RecipeOutcome.Failed;
            using (var archive = opened.Archive)
            {
                context.Say("opened from a stream that cannot seek: {0} entries", archive.Entries.Count);

                // 3. Cancel before extracting: the task completes, and the result says so.
                using (var cancellation = new CancellationTokenSource())
                {
                    cancellation.Cancel();
                    var cancelled = await archive.ExtractAllAsync(context.PathTo("cancelled"), null, cancellation.Token);
                    context.Say("a cancelled extraction returned {0}", cancelled.ErrorCode);
                    if (cancelled.ErrorCode != ErrorCode.Cancelled) return RecipeOutcome.Failed;
                }

                var extracted = await archive.ExtractAllAsync(context.PathTo("unpacked"));
                context.Say("then extracted: {0}", extracted.Succeeded ? "succeeded" : extracted.ToString());
                if (!extracted.Succeeded) return RecipeOutcome.Failed;
            }

            return File.Exists(Path.Combine(context.PathTo("unpacked"), "readme.txt")) ? RecipeOutcome.Passed : RecipeOutcome.Failed;
        }

        /// <summary>A stream as ASP.NET Core's bodies are by default: no seeking, and no synchronous reads or writes.</summary>
        private sealed class AsyncOnlyStream : Stream
        {
            private readonly Stream _inner;

            public AsyncOnlyStream(Stream inner) => _inner = inner;

            public override bool CanRead => true;
            public override bool CanSeek => false;
            public override bool CanWrite => true;
            public override long Length => throw new NotSupportedException();

            public override long Position
            {
                get => throw new NotSupportedException();
                set => throw new NotSupportedException();
            }

            public override void Flush() => throw new InvalidOperationException("Synchronous operations are disallowed.");
            public override Task FlushAsync(CancellationToken cancellationToken) => Task.CompletedTask;
            public override int Read(byte[] buffer, int offset, int count) => throw new InvalidOperationException("Synchronous operations are disallowed.");
            public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) => _inner.ReadAsync(buffer, offset, count, cancellationToken);
            public override void Write(byte[] buffer, int offset, int count) => throw new InvalidOperationException("Synchronous operations are disallowed.");
            public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) => _inner.WriteAsync(buffer, offset, count, cancellationToken);
#if NETCOREAPP2_1_OR_GREATER
            public override ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default) => _inner.ReadAsync(buffer, cancellationToken);
            public override ValueTask WriteAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken = default) => _inner.WriteAsync(buffer, cancellationToken);
#endif
            public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();
            public override void SetLength(long value) => throw new NotSupportedException();
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Text
Imports Bastion.Archive
Imports Bastion.Archive.Codecs

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Compress and decompress with bzip2, and see what the level actually buys.
    ''' </summary>
    ''' <remarks>
    ''' bzip2's level is not an effort dial in the way gzip's is: it is the **block size**, a hundred kilobytes
    ''' per step, and it is the size of the window the Burrows–Wheeler transform sorts. That is why the level
    ''' decides how much memory the codec holds as well as how well it compresses, and why raising it does
    ''' nothing at all for a file smaller than one block — there is no second block for the extra room to hold.
    ''' <para>
    ''' Like gzip, a <c>.bz2</c> file may be several streams concatenated, and this reads them as one.
    ''' </para>
    ''' </remarks>
    Friend Module BZip2StreamUsageRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim content = Encoding.UTF8.GetBytes(
                GZipStreamUsageRecipe.Repeat("the quick brown fox jumps over the lazy dog. ", 4000))

            For Each level In New Integer() {1, 5, 9}
                Dim compressedPath = context.PathTo("notes-" & level.ToString(Globalization.CultureInfo.InvariantCulture) & ".bz2")
                Dim held As Long
                Using file As New FileStream(compressedPath, FileMode.Create, FileAccess.Write)
                    Using writer As New BZip2EncoderStream(file, level, leaveOpen:=True)
                        held = writer.WorkingMemoryBytes
                        writer.Write(content, 0, content.Length)
                    End Using
                End Using
                context.Say("level {0}: {1} -> {2}, holding {3} while it works",
                            level, RecipeContext.Readable(content.Length),
                            RecipeContext.Readable(New FileInfo(compressedPath).Length),
                            RecipeContext.Readable(held))

                Using file As New FileStream(compressedPath, FileMode.Open, FileAccess.Read)
                    Using reader As New BZip2DecoderStream(file, leaveOpen:=True)
                        Using produced As New MemoryStream()
                            GZipStreamUsageRecipe.CopyAll(reader, produced)
                            If Not RecipeContext.SameBytes(content, produced.ToArray()) Then
                                context.Say("level {0} did not come back the same", level)
                                Return RecipeOutcome.Failed
                            End If
                        End Using
                    End Using
                End Using
            Next

            ' Three streams in one file, which is what happens when .bz2 files are concatenated.
            Dim joinedPath = context.PathTo("joined.bz2")
            Dim parts = New String() {"first", "second", "third"}
            Using file As New FileStream(joinedPath, FileMode.Create, FileAccess.Write)
                For Each part In parts
                    Dim bytes = Encoding.UTF8.GetBytes(part & Environment.NewLine)
                    Using writer As New BZip2EncoderStream(file, 1, leaveOpen:=True)
                        writer.Write(bytes, 0, bytes.Length)
                    End Using
                Next
            End Using

            Using file As New FileStream(joinedPath, FileMode.Open, FileAccess.Read)
                Using reader As New BZip2DecoderStream(file, leaveOpen:=True)
                    Using produced As New MemoryStream()
                        GZipStreamUsageRecipe.CopyAll(reader, produced)
                        Dim text = Encoding.UTF8.GetString(produced.ToArray())
                        Dim expected = String.Join(Environment.NewLine, parts) & Environment.NewLine
                        If Not String.Equals(text, expected, StringComparison.Ordinal) Then
                            context.Say("three joined streams read back as: " & text.Replace(Environment.NewLine, "|"))
                            Return RecipeOutcome.Failed
                        End If
                        context.Say("three joined streams read as one")
                    End Using
                End Using
            End Using

            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.Globalization;
using System.IO;
using System.Text;
using Bastion.Archive.Codecs;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Compress and decompress with bzip2, and see what the level actually buys.
    /// </summary>
    /// <remarks>
    /// bzip2's level is not an effort dial in the way gzip's is: it is the <b>block size</b>, a hundred
    /// kilobytes per step, and it is the size of the window the Burrows–Wheeler transform sorts. That is why
    /// the level decides how much memory the codec holds as well as how well it compresses, and why raising it
    /// does nothing at all for a file smaller than one block — there is no second block for the extra room to
    /// hold.
    /// <para>
    /// Like gzip, a <c>.bz2</c> file may be several streams concatenated, and this reads them as one.
    /// </para>
    /// </remarks>
    internal static class BZip2StreamUsageRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var content = Encoding.UTF8.GetBytes(
                GZipStreamUsageRecipe.Repeat("the quick brown fox jumps over the lazy dog. ", 4000));

            foreach (var level in new[] { 1, 5, 9 })
            {
                var compressedPath = context.PathTo("notes-" + level.ToString(CultureInfo.InvariantCulture) + ".bz2");
                long held;
                using (var file = new FileStream(compressedPath, FileMode.Create, FileAccess.Write))
                using (var writer = new BZip2EncoderStream(file, level, leaveOpen: true))
                {
                    held = writer.WorkingMemoryBytes;
                    writer.Write(content, 0, content.Length);
                }

                context.Say("level {0}: {1} -> {2}, holding {3} while it works",
                    level, RecipeContext.Readable(content.Length),
                    RecipeContext.Readable(new FileInfo(compressedPath).Length),
                    RecipeContext.Readable(held));

                using (var file = new FileStream(compressedPath, FileMode.Open, FileAccess.Read))
                using (var reader = new BZip2DecoderStream(file, leaveOpen: true))
                using (var produced = new MemoryStream())
                {
                    GZipStreamUsageRecipe.CopyAll(reader, produced);
                    if (!RecipeContext.SameBytes(content, produced.ToArray()))
                    {
                        context.Say("level {0} did not come back the same", level);
                        return RecipeOutcome.Failed;
                    }
                }
            }

            // Three streams in one file, which is what happens when .bz2 files are concatenated.
            var joinedPath = context.PathTo("joined.bz2");
            var parts = new[] { "first", "second", "third" };
            using (var file = new FileStream(joinedPath, FileMode.Create, FileAccess.Write))
            {
                foreach (var part in parts)
                {
                    var bytes = Encoding.UTF8.GetBytes(part + Environment.NewLine);
                    using (var writer = new BZip2EncoderStream(file, 1, leaveOpen: true))
                    {
                        writer.Write(bytes, 0, bytes.Length);
                    }
                }
            }

            using (var file = new FileStream(joinedPath, FileMode.Open, FileAccess.Read))
            using (var reader = new BZip2DecoderStream(file, leaveOpen: true))
            using (var produced = new MemoryStream())
            {
                GZipStreamUsageRecipe.CopyAll(reader, produced);
                var text = Encoding.UTF8.GetString(produced.ToArray());
                var expected = string.Join(Environment.NewLine, parts) + Environment.NewLine;
                if (!string.Equals(text, expected, StringComparison.Ordinal))
                {
                    context.Say("three joined streams read back as: " + text.Replace(Environment.NewLine, "|"));
                    return RecipeOutcome.Failed;
                }

                context.Say("three joined streams read as one");
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.FileSystem

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Convert a ZIP to a 7z by copying one archive folder into another, with nothing written to disk in between.
    ''' </summary>
    ''' <remarks>
    ''' Each entry is streamed out of the ZIP, its checksum verified, and into the 7z, which is written once. The
    ''' same call copies between any two archives, and a nested archive — a file inside another archive — can be
    ''' opened as a folder too, up to <c>ExtractionPolicy.MaxNestingDepth</c> levels deep.
    ''' </remarks>
    Friend Module CopyArchiveToArchiveRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source As New DiskFolder(context.CreateSampleTree())
            Dim zip As New ArchiveFolder(New DiskFile(context.PathTo("books.zip")))
            If Not source.CopyFilesTo(zip, Nothing).Succeeded Then Return RecipeOutcome.Failed

            Dim sevenZip As New ArchiveFolder(New DiskFile(context.PathTo("books.7z")))
            Dim converted = zip.CopyFilesTo(sevenZip, Nothing)
            If Not converted.Succeeded Then
                context.Say(converted.ToString())
                Return RecipeOutcome.Failed
            End If
            context.Say("books.zip {0} became books.7z {1}",
                        RecipeContext.Readable(New FileInfo(zip.FullName).Length),
                        RecipeContext.Readable(New FileInfo(sevenZip.FullName).Length))

            ' Put the ZIP inside the 7z and read a file out of it through two archives at once.
            If Not zip.ArchiveFile.CopyTo(sevenZip, Nothing).Succeeded Then Return RecipeOutcome.Failed
            Dim nested As New ArchiveFolder(sevenZip.GetFile("books.zip"))
            Dim opened = nested.GetFile("readme.txt").OpenRead()
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using reader As New StreamReader(opened.Stream)
                context.Say("read through two archives: ""{0}""", reader.ReadToEnd())
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System.IO;
using Bastion.Archive.FileSystem;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Convert a ZIP to a 7z by copying one archive folder into another, with nothing written to disk in between.
    /// </summary>
    /// <remarks>
    /// Each entry is streamed out of the ZIP, its checksum verified, and into the 7z, which is written once. The
    /// same call copies between any two archives, and a nested archive — a file inside another archive — can be
    /// opened as a folder too, up to <c>ExtractionPolicy.MaxNestingDepth</c> levels deep.
    /// </remarks>
    internal static class CopyArchiveToArchiveRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = new DiskFolder(context.CreateSampleTree());
            var zip = new ArchiveFolder(new DiskFile(context.PathTo("books.zip")));
            if (!source.CopyFilesTo(zip, null).Succeeded) return RecipeOutcome.Failed;

            var sevenZip = new ArchiveFolder(new DiskFile(context.PathTo("books.7z")));
            var converted = zip.CopyFilesTo(sevenZip, null);
            if (!converted.Succeeded)
            {
                context.Say(converted.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say("books.zip {0} became books.7z {1}",
                        RecipeContext.Readable(new FileInfo(zip.FullName).Length),
                        RecipeContext.Readable(new FileInfo(sevenZip.FullName).Length));

            // Put the ZIP inside the 7z and read a file out of it through two archives at once.
            if (!zip.ArchiveFile.CopyTo(sevenZip, null).Succeeded) return RecipeOutcome.Failed;
            var nested = new ArchiveFolder(sevenZip.GetFile("books.zip"));
            var opened = nested.GetFile("readme.txt").OpenRead();
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var reader = new StreamReader(opened.Stream))
            {
                context.Say("read through two archives: \"{0}\"", reader.ReadToEnd());
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.FileSystem

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Zip and unzip by copying folders: a disk folder into an archive, and the archive back out.
    ''' </summary>
    ''' <remarks>
    ''' In the FileSystem model an archive is a folder (<see cref="ArchiveFolder"/>), so zipping is copying into it
    ''' and unzipping is copying out of it — the same call either way, and the same as copying between two disk
    ''' folders. The archive's name decides its format, so ".7z" here would give a 7z with no other change. Copying
    ''' out canonicalises every name the way extraction does, so an archive cannot steer a file outside the folder
    ''' it is copied to.
    ''' </remarks>
    Friend Module CopyDiskFolderToArchiveRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source As New DiskFolder(context.CreateSampleTree())
            Dim archive As New ArchiveFolder(New DiskFile(context.PathTo("books.zip")))

            Dim zipped = source.CopyFilesTo(archive, Nothing)
            If Not zipped.Succeeded Then
                context.Say(zipped.ToString())
                Return RecipeOutcome.Failed
            End If
            context.Say("zipped into {0}: {1}", archive.Name, RecipeContext.Readable(New FileInfo(archive.FullName).Length))

            Dim listed = archive.GetItems(True)
            If Not listed.Succeeded Then Return RecipeOutcome.Failed
            For Each item In listed.Items
                Dim file = TryCast(item, ArchivedFile)
                context.Say("  {0}", If(file IsNot Nothing, file.PathInArchive, DirectCast(item, ArchivedFolder).PathInArchive & "/"))
            Next

            Dim target As New DiskFolder(context.PathTo("unzipped"))
            Dim unzipped = archive.CopyFilesTo(target, Nothing)
            If Not unzipped.Succeeded Then
                context.Say(unzipped.ToString())
                Return RecipeOutcome.Failed
            End If
            If Not SevenZipCreateRecipe.SameTree(source.FullName, target.FullName, context) Then Return RecipeOutcome.Failed
            context.Say("copied back out, every file the same")
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System.IO;
using Bastion.Archive.FileSystem;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Zip and unzip by copying folders: a disk folder into an archive, and the archive back out.
    /// </summary>
    /// <remarks>
    /// In the FileSystem model an archive is a folder (<see cref="ArchiveFolder"/>), so zipping is copying into it
    /// and unzipping is copying out of it — the same call either way, and the same as copying between two disk
    /// folders. The archive's name decides its format, so ".7z" here would give a 7z with no other change. Copying
    /// out canonicalises every name the way extraction does, so an archive cannot steer a file outside the folder
    /// it is copied to.
    /// </remarks>
    internal static class CopyDiskFolderToArchiveRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = new DiskFolder(context.CreateSampleTree());
            var archive = new ArchiveFolder(new DiskFile(context.PathTo("books.zip")));

            var zipped = source.CopyFilesTo(archive, null);
            if (!zipped.Succeeded)
            {
                context.Say(zipped.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say("zipped into {0}: {1}", archive.Name, RecipeContext.Readable(new FileInfo(archive.FullName).Length));

            var listed = archive.GetItems(true);
            if (!listed.Succeeded) return RecipeOutcome.Failed;
            foreach (var item in listed.Items)
            {
                var file = item as ArchivedFile;
                context.Say("  {0}", file != null ? file.PathInArchive : ((ArchivedFolder)item).PathInArchive + "/");
            }

            var target = new DiskFolder(context.PathTo("unzipped"));
            var unzipped = archive.CopyFilesTo(target, null);
            if (!unzipped.Succeeded)
            {
                context.Say(unzipped.ToString());
                return RecipeOutcome.Failed;
            }

            if (!SevenZipCreateRecipe.SameTree(source.FullName, target.FullName, context)) return RecipeOutcome.Failed;
            context.Say("copied back out, every file the same");
            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Security
Imports Bastion.Archive.Sfx

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Dress a self-extractor: its own title, message, licence, suggested folder, icon, and a file to open afterwards.
    ''' </summary>
    ''' <remarks>
    ''' Everything here ends up in the program's window when it is double-clicked. The icon is written into the program
    ''' itself, so Explorer shows it too; it is done in managed code, so a build server on Linux makes the same program.
    ''' The recipe does not run the program — its window would wait for someone to click — but reads its settings back,
    ''' which is also how a tool can tell what an unknown self-extractor will do.
    ''' </remarks>
    Friend Module CreateSfxCustomDialogRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim iconPath = context.PathTo("brand.ico")
            File.WriteAllBytes(iconPath, SolidIcon(&H1F, &H3A, &H5F))
            Dim options As New SelfExtractorOptions() With {
                .Title = "Contoso report pack",
                .Prompt = "The quarterly reports will be copied to the folder below.",
                .LicenceText = "These reports are confidential." & Environment.NewLine & "Do not forward them outside the company.",
                .DefaultDirectory = "%USERPROFILE%\Documents\Contoso reports",
                .RunAfterExtraction = "readme.txt",
                .Overwrite = OverwriteMode.Ask,
                .IconPath = iconPath
            }
            Dim executable = context.PathTo("reports.exe")
            Dim started = ArchiveWriter.CreateSelfExtracting(executable, options, Nothing, Nothing)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                If Not writer.AddDirectory(source, Nothing, Nothing).Succeeded OrElse Not writer.Complete().Succeeded Then Return RecipeOutcome.Failed
            End Using

            Using opened = Archive.Open(executable).Archive
                Dim carried = opened.SelfExtractor.Options
                context.Say("title:      {0}", carried.Title)
                context.Say("prompt:     {0}", carried.Prompt)
                context.Say("licence:    {0} lines", carried.LicenceText.Split(New String() {Environment.NewLine}, StringSplitOptions.None).Length)
                context.Say("folder:     {0}", carried.DefaultDirectory)
                context.Say("afterwards: {0}", carried.RunAfterExtraction)
                context.Say("overwrite:  {0}", carried.Overwrite)
                Return If(carried.Title = options.Title, RecipeOutcome.Passed, RecipeOutcome.Failed)
            End Using
        End Function

        ''' <summary>A one-image 16-pixel icon in one colour; a real application would ship its own .ico.</summary>
        Private Function SolidIcon(red As Byte, green As Byte, blue As Byte) As Byte()
            Dim image(40 + 16 * 16 * 4 + 16 * 4 - 1) As Byte
            BitConverter.GetBytes(40).CopyTo(image, 0)
            BitConverter.GetBytes(16).CopyTo(image, 4)
            BitConverter.GetBytes(32).CopyTo(image, 8)
            BitConverter.GetBytes(CShort(1)).CopyTo(image, 12)
            BitConverter.GetBytes(CShort(32)).CopyTo(image, 14)
            For index = 0 To 16 * 16 - 1
                image(40 + index * 4) = blue
                image(40 + index * 4 + 1) = green
                image(40 + index * 4 + 2) = red
                image(40 + index * 4 + 3) = 255
            Next
            Dim icon(22 + image.Length - 1) As Byte
            BitConverter.GetBytes(CShort(1)).CopyTo(icon, 2)
            BitConverter.GetBytes(CShort(1)).CopyTo(icon, 4)
            icon(6) = 16
            icon(7) = 16
            BitConverter.GetBytes(CShort(1)).CopyTo(icon, 10)
            BitConverter.GetBytes(CShort(32)).CopyTo(icon, 12)
            BitConverter.GetBytes(image.Length).CopyTo(icon, 14)
            BitConverter.GetBytes(22).CopyTo(icon, 18)
            image.CopyTo(icon, 22)
            Return icon
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;
using Bastion.Archive.Security;
using Bastion.Archive.Sfx;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Dress a self-extractor: its own title, message, licence, suggested folder, icon, and a file to open afterwards.
    /// </summary>
    /// <remarks>
    /// Everything here ends up in the program's window when it is double-clicked. The icon is written into the program
    /// itself, so Explorer shows it too; it is done in managed code, so a build server on Linux makes the same program.
    /// The recipe does not run the program — its window would wait for someone to click — but reads its settings back,
    /// which is also how a tool can tell what an unknown self-extractor will do.
    /// </remarks>
    internal static class CreateSfxCustomDialogRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var iconPath = context.PathTo("brand.ico");
            File.WriteAllBytes(iconPath, SolidIcon(0x1F, 0x3A, 0x5F));
            var options = new SelfExtractorOptions
            {
                Title = "Contoso report pack",
                Prompt = "The quarterly reports will be copied to the folder below.",
                LicenceText = "These reports are confidential." + Environment.NewLine + "Do not forward them outside the company.",
                DefaultDirectory = @"%USERPROFILE%\Documents\Contoso reports",
                RunAfterExtraction = "readme.txt",
                Overwrite = OverwriteMode.Ask,
                IconPath = iconPath,
            };
            var executable = context.PathTo("reports.exe");
            var started = ArchiveWriter.CreateSelfExtracting(executable, options, null, null);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                if (!writer.AddDirectory(source, null, null).Succeeded || !writer.Complete().Succeeded) return RecipeOutcome.Failed;
            }

            using (var archive = Archive.Open(executable).Archive)
            {
                var carried = archive.SelfExtractor.Options;
                context.Say("title:      {0}", carried.Title);
                context.Say("prompt:     {0}", carried.Prompt);
                context.Say("licence:    {0} lines", carried.LicenceText.Split(new[] { Environment.NewLine }, StringSplitOptions.None).Length);
                context.Say("folder:     {0}", carried.DefaultDirectory);
                context.Say("afterwards: {0}", carried.RunAfterExtraction);
                context.Say("overwrite:  {0}", carried.Overwrite);
                return carried.Title == options.Title ? RecipeOutcome.Passed : RecipeOutcome.Failed;
            }
        }

        /// <summary>A one-image 16-pixel icon in one colour; a real application would ship its own .ico.</summary>
        private static byte[] SolidIcon(byte red, byte green, byte blue)
        {
            var image = new byte[40 + 16 * 16 * 4 + 16 * 4];
            BitConverter.GetBytes(40).CopyTo(image, 0);
            BitConverter.GetBytes(16).CopyTo(image, 4);
            BitConverter.GetBytes(32).CopyTo(image, 8);
            BitConverter.GetBytes((short)1).CopyTo(image, 12);
            BitConverter.GetBytes((short)32).CopyTo(image, 14);
            for (var index = 0; index < 16 * 16; index++)
            {
                image[40 + index * 4] = blue;
                image[40 + index * 4 + 1] = green;
                image[40 + index * 4 + 2] = red;
                image[40 + index * 4 + 3] = 255;
            }

            var icon = new byte[22 + image.Length];
            BitConverter.GetBytes((short)1).CopyTo(icon, 2);
            BitConverter.GetBytes((short)1).CopyTo(icon, 4);
            icon[6] = 16;
            icon[7] = 16;
            BitConverter.GetBytes((short)1).CopyTo(icon, 10);
            BitConverter.GetBytes((short)32).CopyTo(icon, 12);
            BitConverter.GetBytes(image.Length).CopyTo(icon, 14);
            BitConverter.GetBytes(22).CopyTo(icon, 18);
            image.CopyTo(icon, 22);
            return icon;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Diagnostics
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Sfx

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Make a self-extracting archive: one program that unpacks itself, which every ZIP tool also opens as a ZIP.
    ''' </summary>
    ''' <remarks>
    ''' <c>CreateSelfExtracting</c> takes the same entries as any archive. The program needs nothing installed beyond
    ''' what Windows 10 and 11 carry, runs natively on x64 and ARM64, and is run here from its command line — <c>-s</c>
    ''' for silent, <c>-d</c> for the folder — to show it working; double-clicked, it opens its window instead.
    ''' </remarks>
    Friend Module CreateSfxRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim executable = context.PathTo("package.exe")
            Dim started = ArchiveWriter.CreateSelfExtracting(executable, New SelfExtractorOptions() With {.Title = "Sample package"}, Nothing, Nothing)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                If Not writer.AddDirectory(source, Nothing, Nothing).Succeeded OrElse Not writer.Complete().Succeeded Then Return RecipeOutcome.Failed
            End Using
            context.Say("wrote package.exe, {0} KiB", New FileInfo(executable).Length \ 1024)

            ' It is also a ZIP archive, readable as one.
            Using opened = Archive.Open(executable).Archive
                context.Say("opened as an archive: {0} entries after a {1} KiB program", opened.Entries.Count, opened.SelfExtractor.PrefixLength \ 1024)
            End Using

            ' Run it the way a script would.
            Dim target = context.PathTo("unpacked")
            Using process = System.Diagnostics.Process.Start(New ProcessStartInfo(executable, $"-s -d ""{target}""") With {.UseShellExecute = False, .CreateNoWindow = True})
                process.WaitForExit()
                context.Say("package.exe -s exited with {0}", process.ExitCode)
                If process.ExitCode <> 0 Then Return RecipeOutcome.Failed
            End Using
            Return If(File.Exists(Path.Combine(target, "readme.txt")), RecipeOutcome.Passed, RecipeOutcome.Failed)
        End Function

    End Module

End Namespace

C#

using System.Diagnostics;
using System.IO;
using Bastion.Archive.Sfx;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Make a self-extracting archive: one program that unpacks itself, which every ZIP tool also opens as a ZIP.
    /// </summary>
    /// <remarks>
    /// <c>CreateSelfExtracting</c> takes the same entries as any archive. The program needs nothing installed beyond
    /// what Windows 10 and 11 carry, runs natively on x64 and ARM64, and is run here from its command line — <c>-s</c>
    /// for silent, <c>-d</c> for the folder — to show it working; double-clicked, it opens its window instead.
    /// </remarks>
    internal static class CreateSfxRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var executable = context.PathTo("package.exe");
            var started = ArchiveWriter.CreateSelfExtracting(executable, new SelfExtractorOptions { Title = "Sample package" }, null, null);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                if (!writer.AddDirectory(source, null, null).Succeeded || !writer.Complete().Succeeded) return RecipeOutcome.Failed;
            }

            context.Say("wrote package.exe, {0} KiB", new FileInfo(executable).Length / 1024);

            // It is also a ZIP archive, readable as one.
            using (var archive = Archive.Open(executable).Archive)
            {
                context.Say("opened as an archive: {0} entries after a {1} KiB program", archive.Entries.Count, archive.SelfExtractor.PrefixLength / 1024);
            }

            // Run it the way a script would.
            var target = context.PathTo("unpacked");
            using (var process = Process.Start(new ProcessStartInfo(executable, $"-s -d \"{target}\"") { UseShellExecute = false, CreateNoWindow = true }))
            {
                process.WaitForExit();
                context.Say("package.exe -s exited with {0}", process.ExitCode);
                if (process.ExitCode != 0) return RecipeOutcome.Failed;
            }

            return File.Exists(Path.Combine(target, "readme.txt")) ? RecipeOutcome.Passed : RecipeOutcome.Failed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Diagnostics
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Security
Imports Bastion.Archive.Sfx

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' A self-extractor that never shows a window: it unpacks to the folder it was given and reports by exit code.
    ''' </summary>
    ''' <remarks>
    ''' For deployment scripts and installers. <c>DefaultDirectory</c> may use environment variables such as
    ''' <c>%ProgramData%</c>, expanded on the machine that runs it. Nothing already there is replaced unless
    ''' <c>Overwrite</c> says so, and the exit code is 0 done, 1 failed, 2 cancelled — here the second run fails,
    ''' because the files from the first are still there.
    ''' </remarks>
    Friend Module CreateSfxSilentRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim target = context.PathTo("deployed")
            Dim executable = context.PathTo("deploy.exe")
            Dim options As New SelfExtractorOptions() With {.Silent = True, .DefaultDirectory = target, .Overwrite = OverwriteMode.FailIfExists}
            Dim started = ArchiveWriter.CreateSelfExtracting(executable, options, Nothing, Nothing)
            If Not started.Succeeded Then Return RecipeOutcome.Failed
            Using writer = started.Writer
                If Not writer.AddDirectory(source, Nothing, Nothing).Succeeded OrElse Not writer.Complete().Succeeded Then Return RecipeOutcome.Failed
            End Using

            Dim first = RunOnce(executable)
            context.Say("first run exited with {0}; readme.txt is {1}", first, If(File.Exists(Path.Combine(target, "readme.txt")), "there", "missing"))
            Dim second = RunOnce(executable)
            context.Say("second run exited with {0}: the files were already there", second)
            Return If(first = 0 AndAlso second = 1, RecipeOutcome.Passed, RecipeOutcome.Failed)
        End Function

        Private Function RunOnce(executable As String) As Integer
            Using process = System.Diagnostics.Process.Start(New ProcessStartInfo(executable) With {.UseShellExecute = False, .CreateNoWindow = True})
                process.WaitForExit()
                Return process.ExitCode
            End Using
        End Function

    End Module

End Namespace

C#

using System.Diagnostics;
using System.IO;
using Bastion.Archive.Security;
using Bastion.Archive.Sfx;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// A self-extractor that never shows a window: it unpacks to the folder it was given and reports by exit code.
    /// </summary>
    /// <remarks>
    /// For deployment scripts and installers. <c>DefaultDirectory</c> may use environment variables such as
    /// <c>%ProgramData%</c>, expanded on the machine that runs it. Nothing already there is replaced unless
    /// <c>Overwrite</c> says so, and the exit code is 0 done, 1 failed, 2 cancelled — here the second run fails,
    /// because the files from the first are still there.
    /// </remarks>
    internal static class CreateSfxSilentRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var target = context.PathTo("deployed");
            var executable = context.PathTo("deploy.exe");
            var options = new SelfExtractorOptions { Silent = true, DefaultDirectory = target, Overwrite = OverwriteMode.FailIfExists };
            var started = ArchiveWriter.CreateSelfExtracting(executable, options, null, null);
            if (!started.Succeeded) return RecipeOutcome.Failed;
            using (var writer = started.Writer)
            {
                if (!writer.AddDirectory(source, null, null).Succeeded || !writer.Complete().Succeeded) return RecipeOutcome.Failed;
            }

            var first = RunOnce(executable);
            context.Say("first run exited with {0}; readme.txt is {1}", first, File.Exists(Path.Combine(target, "readme.txt")) ? "there" : "missing");
            var second = RunOnce(executable);
            context.Say("second run exited with {0}: the files were already there", second);
            return first == 0 && second == 1 ? RecipeOutcome.Passed : RecipeOutcome.Failed;
        }

        private static int RunOnce(string executable)
        {
            using (var process = Process.Start(new ProcessStartInfo(executable) { UseShellExecute = false, CreateNoWindow = true }))
            {
                process.WaitForExit();
                return process.ExitCode;
            }
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Create an archive from a handful of files.
    ''' </summary>
    ''' <remarks>
    ''' Three things in this recipe are the library's whole contract in miniature. Nothing throws — every call
    ''' hands back an <see cref="OperationResult"/> to look at. The archive is not an archive until
    ''' <c>Complete</c> returns, because until then it is a temporary neighbour of the file you asked for, so a
    ''' crash leaves no half-written archive that looks whole. And <c>Create</c> refuses to write
    ''' over a file that already exists, which you have to ask for rather than get by accident.
    ''' </remarks>
    Friend Module CreateZipRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("created.zip")

            ' Level 6 is the default; naming it makes the recipe explicit about where the setting lives.
            Dim settings As New CompressionSettings() With {.Level = 6}
            Dim started = ArchiveWriter.Create(archivePath, settings)
            If Not started.Succeeded Then
                context.Say("could not start the archive: " & started.ToString())
                Return RecipeOutcome.Failed
            End If

            Using writer = started.Writer
                For Each name In New String() {"readme.txt", "data.bin"}
                    Dim added = writer.AddFile(Path.Combine(source, name), name)
                    If Not added.Succeeded Then
                        context.Say("could not add " & name & ": " & added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                Next
                ' A stream is a first-class source: nothing has to exist on disk to go into an archive.
                Using generated As New MemoryStream(RecipeContext.PseudoRandom(4096, 99))
                    Dim added = writer.AddStream(generated, "generated/noise.bin", Nothing)
                    If Not added.Succeeded Then
                        context.Say("could not add the generated entry: " & added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                End Using

                writer.Comment = "Written by the Bastion Archive SDK cookbook."
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say("could not finish the archive: " & finished.ToString())
                    Return RecipeOutcome.Failed
                End If
                context.Say("wrote {0} entries in {1:N0} ms", writer.EntryCount, finished.Elapsed.TotalMilliseconds)
            End Using

            ' Writing over an existing archive is refused, not silently done.
            Dim again = ArchiveWriter.Create(archivePath)
            If again.Succeeded Then
                again.Writer.Dispose()
                context.Say("the second Create should have been refused")
                Return RecipeOutcome.Failed
            End If
            context.Say("a second Create on the same path returned " & again.ErrorCode.ToString())

            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say("could not reopen the archive: " & opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim packed = 0L
                Dim unpacked = 0L
                For Each entry In archive.Entries
                    packed += entry.CompressedSize
                    unpacked += entry.Size
                Next
                context.Say("{0} entries, {1} in, {2} on disk, comment {3}",
                            archive.Entries.Count, RecipeContext.Readable(unpacked),
                            RecipeContext.Readable(packed),
                            If(archive.Comment.Length > 0, "present", "absent"))
                If archive.Entries.Count <> 3 Then Return RecipeOutcome.Failed
                If archive.Comment.Length = 0 Then Return RecipeOutcome.Failed
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Create an archive from a handful of files.
    /// </summary>
    /// <remarks>
    /// Three things in this recipe are the library's whole contract in miniature. Nothing throws — every call
    /// hands back an <see cref="OperationResult"/> to look at. The archive is not an archive until
    /// <c>Complete</c> returns, because until then it is a temporary neighbour of the file you asked for, so a
    /// crash leaves no half-written archive that looks whole. And <c>Create</c> refuses to write
    /// over a file that already exists, which you have to ask for rather than get by accident.
    /// </remarks>
    internal static class CreateZipRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("created.zip");

            // Level 6 is the default; naming it makes the recipe explicit about where the setting lives.
            var settings = new CompressionSettings { Level = 6 };
            var started = ArchiveWriter.Create(archivePath, settings);
            if (!started.Succeeded)
            {
                context.Say("could not start the archive: " + started);
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                foreach (var name in new[] { "readme.txt", "data.bin" })
                {
                    var added = writer.AddFile(Path.Combine(source, name), name);
                    if (!added.Succeeded)
                    {
                        context.Say("could not add " + name + ": " + added);
                        return RecipeOutcome.Failed;
                    }
                }

                // A stream is a first-class source: nothing has to exist on disk to go into an archive.
                using (var generated = new MemoryStream(RecipeContext.PseudoRandom(4096, 99)))
                {
                    var added = writer.AddStream(generated, "generated/noise.bin", null);
                    if (!added.Succeeded)
                    {
                        context.Say("could not add the generated entry: " + added);
                        return RecipeOutcome.Failed;
                    }
                }

                writer.Comment = "Written by the Bastion Archive SDK cookbook.";
                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say("could not finish the archive: " + finished);
                    return RecipeOutcome.Failed;
                }

                context.Say("wrote {0} entries in {1:N0} ms", writer.EntryCount, finished.Elapsed.TotalMilliseconds);
            }

            // Writing over an existing archive is refused, not silently done.
            var again = ArchiveWriter.Create(archivePath);
            if (again.Succeeded)
            {
                again.Writer.Dispose();
                context.Say("the second Create should have been refused");
                return RecipeOutcome.Failed;
            }

            context.Say("a second Create on the same path returned " + again.ErrorCode);

            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say("could not reopen the archive: " + opened);
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var packed = 0L;
                var unpacked = 0L;
                foreach (var entry in archive.Entries)
                {
                    packed += entry.CompressedSize;
                    unpacked += entry.Size;
                }

                context.Say("{0} entries, {1} in, {2} on disk, comment {3}",
                    archive.Entries.Count, RecipeContext.Readable(unpacked), RecipeContext.Readable(packed),
                    archive.Comment.Length > 0 ? "present" : "absent");
                if (archive.Entries.Count != 3) return RecipeOutcome.Failed;
                if (archive.Comment.Length == 0) return RecipeOutcome.Failed;
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Diagnostics
Imports Bastion.Archive.Security

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Answer the library's questions as they come up: which items to take, what to do about a file that is
    ''' already there, and which password to try.
    ''' </summary>
    ''' <remarks>
    ''' Every question is an event on <see cref="OperationMonitor"/>, and every one has a safe answer when nobody
    ''' listens — take the item, refuse to overwrite, give up on the password — so wiring one up changes nothing
    ''' else. Here a first extraction fills a folder, then a second one runs into what it left: one file is written
    ''' under a new name, one is skipped, and one is left out before it is even read. The archive is encrypted and
    ''' the password is supplied only when asked for.
    ''' </remarks>
    Friend Module EventsAndPromptsRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Const password As String = "asked for, not given"
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("prompts.zip")
            Dim started = ArchiveWriter.Create(archivePath, New CompressionSettings() With {.Password = password})
            Using writer = started.Writer
                If Not writer.AddDirectory(source, Nothing, Nothing).Succeeded OrElse Not writer.Complete().Succeeded Then Return RecipeOutcome.Failed
            End Using

            Dim monitor As New OperationMonitor()
            AddHandler monitor.InvalidPassword,
                Sub(sender, e)
                    context.Say("password {0} for {1}: supplying it", If(e.PasswordWasGiven, "refused", "needed"), e.EntryPath)
                    e.NewPassword = password
                End Sub
            AddHandler monitor.PreviewItem,
                Sub(sender, e)
                    If e.ItemPath = "data.bin" Then
                        context.Say("leaving out {0}", e.ItemPath)
                        e.Include = False
                    End If
                End Sub
            AddHandler monitor.ItemExists,
                Sub(sender, e)
                    If e.ItemPath = "readme.txt" Then
                        context.Say("{0} exists: writing it as readme (2).txt", e.ItemPath)
                        e.Decision = ExistsDecision.Rename
                        e.NewName = "readme (2).txt"
                    Else
                        context.Say("{0} exists: skipping it", e.ItemPath)
                        e.Decision = ExistsDecision.Skip
                    End If
                End Sub

            Dim target = context.PathTo("unpacked")
            For Each pass In New Integer() {1, 2}
                context.Say("extraction {0}", pass)
                Dim opened = Archive.Open(archivePath, New ArchiveOpenOptions() With {.Monitor = monitor})
                If Not opened.Succeeded Then Return RecipeOutcome.Failed
                Using archive = opened.Archive
                    Dim options As New ExtractionOptions()
                    options.Policy.Overwrite = OverwriteMode.Ask
                    Dim result = archive.ExtractAll(target, options)
                    If Not result.Succeeded Then
                        context.Say(result.ToString())
                        Return RecipeOutcome.Failed
                    End If
                End Using
            Next
            If Not File.Exists(Path.Combine(target, "readme (2).txt")) OrElse File.Exists(Path.Combine(target, "data.bin")) Then Return RecipeOutcome.Failed
            context.Say("both extractions finished; the second answered every question it met")
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System.IO;
using Bastion.Archive.Diagnostics;
using Bastion.Archive.Security;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Answer the library's questions as they come up: which items to take, what to do about a file that is
    /// already there, and which password to try.
    /// </summary>
    /// <remarks>
    /// Every question is an event on <see cref="OperationMonitor"/>, and every one has a safe answer when nobody
    /// listens — take the item, refuse to overwrite, give up on the password — so wiring one up changes nothing
    /// else. Here a first extraction fills a folder, then a second one runs into what it left: one file is written
    /// under a new name, one is skipped, and one is left out before it is even read. The archive is encrypted and
    /// the password is supplied only when asked for.
    /// </remarks>
    internal static class EventsAndPromptsRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            const string password = "asked for, not given";
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("prompts.zip");
            var started = ArchiveWriter.Create(archivePath, new CompressionSettings { Password = password });
            using (var writer = started.Writer)
            {
                if (!writer.AddDirectory(source, null, null).Succeeded || !writer.Complete().Succeeded) return RecipeOutcome.Failed;
            }

            var monitor = new OperationMonitor();
            monitor.InvalidPassword += (sender, e) =>
            {
                context.Say("password {0} for {1}: supplying it", e.PasswordWasGiven ? "refused" : "needed", e.EntryPath);
                e.NewPassword = password;
            };
            monitor.PreviewItem += (sender, e) =>
            {
                if (e.ItemPath == "data.bin")
                {
                    context.Say("leaving out {0}", e.ItemPath);
                    e.Include = false;
                }
            };
            monitor.ItemExists += (sender, e) =>
            {
                if (e.ItemPath == "readme.txt")
                {
                    context.Say("{0} exists: writing it as readme (2).txt", e.ItemPath);
                    e.Decision = ExistsDecision.Rename;
                    e.NewName = "readme (2).txt";
                }
                else
                {
                    context.Say("{0} exists: skipping it", e.ItemPath);
                    e.Decision = ExistsDecision.Skip;
                }
            };

            var target = context.PathTo("unpacked");
            foreach (var pass in new[] { 1, 2 })
            {
                context.Say("extraction {0}", pass);
                var opened = Archive.Open(archivePath, new ArchiveOpenOptions { Monitor = monitor });
                if (!opened.Succeeded) return RecipeOutcome.Failed;
                using (var archive = opened.Archive)
                {
                    var options = new ExtractionOptions();
                    options.Policy.Overwrite = OverwriteMode.Ask;
                    var result = archive.ExtractAll(target, options);
                    if (!result.Succeeded)
                    {
                        context.Say(result.ToString());
                        return RecipeOutcome.Failed;
                    }
                }
            }

            if (!File.Exists(Path.Combine(target, "readme (2).txt")) || File.Exists(Path.Combine(target, "data.bin"))) return RecipeOutcome.Failed;
            context.Say("both extractions finished; the second answered every question it met");
            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Collections.Generic
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Extract only the entries you choose.
    ''' </summary>
    ''' <remarks>
    ''' There is no pattern language to learn: <c>Extract</c> takes entries from <c>Entries</c>, so the selection
    ''' is ordinary code over ordinary objects — a name test, a size test, a date test, a dialogue's checked
    ''' items. An entry from a different archive is refused with <c>EntryNotFound</c> rather than quietly
    ''' extracting whatever happens to sit at that index.
    ''' <c>ExtractToStream</c> is the other half: one entry, straight into memory or into a network stream, with
    ''' the checksum still verified on the way past.
    ''' </remarks>
    Friend Module ExtractSelectiveRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("selective.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, Nothing, Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim wanted As New List(Of ArchiveEntry)()
                For Each entry In archive.Entries
                    If Not entry.IsDirectory AndAlso entry.Name.EndsWith(".txt", StringComparison.OrdinalIgnoreCase) Then
                        wanted.Add(entry)
                    End If
                Next
                context.Say("{0} of {1} entries are text files", wanted.Count, archive.Entries.Count)

                Dim target = context.PathTo("out")
                Dim extracted = archive.Extract(wanted, target, Nothing)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim produced = Directory.GetFiles(target, "*", SearchOption.AllDirectories)
                context.Say("the output holds {0} files", produced.Length)
                If produced.Length <> wanted.Count Then
                    context.Say("the output should hold exactly what was asked for")
                    Return RecipeOutcome.Failed
                End If
                If File.Exists(Path.Combine(target, "data.bin")) Then
                    context.Say("data.bin was not asked for and should not be there")
                    Return RecipeOutcome.Failed
                End If

                ' One entry into memory, without a file anywhere. The checksum is still checked as it streams.
                Dim readme As ArchiveEntry = Nothing
                For Each entry In archive.Entries
                    If String.Equals(entry.Name, "readme.txt", StringComparison.Ordinal) Then readme = entry
                Next
                If readme Is Nothing Then Return RecipeOutcome.Failed
                Using buffer As New MemoryStream()
                    Dim streamed = archive.ExtractToStream(readme, buffer, Nothing)
                    If Not streamed.Succeeded Then
                        context.Say(streamed.ToString())
                        Return RecipeOutcome.Failed
                    End If
                    context.Say("readme.txt into memory: {0} bytes", buffer.Length)
                    If buffer.Length <> readme.Size Then Return RecipeOutcome.Failed
                End Using
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.Collections.Generic;
using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Extract only the entries you choose.
    /// </summary>
    /// <remarks>
    /// There is no pattern language to learn: <c>Extract</c> takes entries from <c>Entries</c>, so the selection
    /// is ordinary code over ordinary objects — a name test, a size test, a date test, a dialogue's checked
    /// items. An entry from a different archive is refused with <c>EntryNotFound</c> rather than quietly
    /// extracting whatever happens to sit at that index.
    /// <c>ExtractToStream</c> is the other half: one entry, straight into memory or into a network stream, with
    /// the checksum still verified on the way past.
    /// </remarks>
    internal static class ExtractSelectiveRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("selective.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, null, null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return RecipeOutcome.Failed;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var wanted = new List<ArchiveEntry>();
                foreach (var entry in archive.Entries)
                {
                    if (!entry.IsDirectory && entry.Name.EndsWith(".txt", StringComparison.OrdinalIgnoreCase))
                    {
                        wanted.Add(entry);
                    }
                }

                context.Say("{0} of {1} entries are text files", wanted.Count, archive.Entries.Count);

                var target = context.PathTo("out");
                var extracted = archive.Extract(wanted, target, null);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                var produced = Directory.GetFiles(target, "*", SearchOption.AllDirectories);
                context.Say("the output holds {0} files", produced.Length);
                if (produced.Length != wanted.Count)
                {
                    context.Say("the output should hold exactly what was asked for");
                    return RecipeOutcome.Failed;
                }

                if (File.Exists(Path.Combine(target, "data.bin")))
                {
                    context.Say("data.bin was not asked for and should not be there");
                    return RecipeOutcome.Failed;
                }

                // One entry into memory, without a file anywhere. The checksum is still checked as it streams.
                ArchiveEntry readme = null;
                foreach (var entry in archive.Entries)
                {
                    if (string.Equals(entry.Name, "readme.txt", StringComparison.Ordinal)) readme = entry;
                }

                if (readme == null) return RecipeOutcome.Failed;
                using (var buffer = new MemoryStream())
                {
                    var streamed = archive.ExtractToStream(readme, buffer, null);
                    if (!streamed.Succeeded)
                    {
                        context.Say(streamed.ToString());
                        return RecipeOutcome.Failed;
                    }

                    context.Say("readme.txt into memory: {0} bytes", buffer.Length);
                    if (buffer.Length != readme.Size) return RecipeOutcome.Failed;
                }
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Security

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Extract every entry and prove the bytes survived.
    ''' </summary>
    ''' <remarks>
    ''' Extraction refuses to overwrite by default: a recipe that
    ''' extracts the same archive twice into the same directory gets an error the second time, and has to say
    ''' <see cref="OverwriteMode.Overwrite"/> to mean it. Each file is written to a temporary neighbour and moved
    ''' into place, so an interrupted extraction never leaves a truncated file wearing the right name.
    ''' </remarks>
    Friend Module ExtractZipRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("to-extract.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then Return Report(context, started)
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, Nothing, Nothing)
                If Not added.Succeeded Then Return Report(context, added)
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then Return Report(context, finished)
            End Using

            Dim target = context.PathTo("out")
            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then Return Report(context, opened)
            Using archive = opened.Archive
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then Return Report(context, extracted)
                context.Say("extracted {0} entries in {1:N0} ms", archive.Entries.Count, extracted.Elapsed.TotalMilliseconds)

                ' The second attempt into the same directory is refused, because overwriting is a decision.
                Dim refused = archive.ExtractAll(target)
                If refused.Succeeded Then
                    context.Say("the second extraction should have been refused")
                    Return RecipeOutcome.Failed
                End If
                context.Say("extracting again returned " & refused.ErrorCode.ToString())

                Dim overwriting As New ExtractionOptions()
                overwriting.Policy.Overwrite = OverwriteMode.Overwrite
                Dim second = archive.ExtractAll(target, overwriting)
                If Not second.Succeeded Then Return Report(context, second)
                context.Say("asking for Overwrite explicitly: " & second.ErrorCode.ToString())
            End Using

            ' Every file that went in came out byte for byte, and the empty directory survived as a directory.
            For Each original In Directory.GetFiles(source, "*", SearchOption.AllDirectories)
                Dim relative = original.Substring(source.Length).TrimStart(Path.DirectorySeparatorChar)
                Dim produced = Path.Combine(target, relative)
                If Not File.Exists(produced) Then
                    context.Say("missing from the output: " & relative)
                    Return RecipeOutcome.Failed
                End If
                If Not RecipeContext.SameBytes(File.ReadAllBytes(original), File.ReadAllBytes(produced)) Then
                    context.Say("differs from the input: " & relative)
                    Return RecipeOutcome.Failed
                End If
            Next
            If Not Directory.Exists(Path.Combine(target, "empty-folder")) Then
                context.Say("the empty directory did not survive")
                Return RecipeOutcome.Failed
            End If
            context.Say("every file matches its input, and the empty directory is still a directory")
            Return RecipeOutcome.Passed
        End Function

        Private Function Report(context As RecipeContext, result As OperationResult) As RecipeOutcome
            context.Say(result.ToString())
            Return RecipeOutcome.Failed
        End Function

    End Module

End Namespace

C#

using System.IO;
using Bastion.Archive.Security;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Extract every entry and prove the bytes survived.
    /// </summary>
    /// <remarks>
    /// Extraction refuses to overwrite by default: a recipe that
    /// extracts the same archive twice into the same directory gets an error the second time, and has to say
    /// <see cref="OverwriteMode.Overwrite"/> to mean it. Each file is written to a temporary neighbour and moved
    /// into place, so an interrupted extraction never leaves a truncated file wearing the right name.
    /// </remarks>
    internal static class ExtractZipRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("to-extract.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded) return Report(context, started);
            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, null, null);
                if (!added.Succeeded) return Report(context, added);
                var finished = writer.Complete();
                if (!finished.Succeeded) return Report(context, finished);
            }

            var target = context.PathTo("out");
            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded) return Report(context, opened);
            using (var archive = opened.Archive)
            {
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded) return Report(context, extracted);
                context.Say("extracted {0} entries in {1:N0} ms", archive.Entries.Count, extracted.Elapsed.TotalMilliseconds);

                // The second attempt into the same directory is refused, because overwriting is a decision.
                var refused = archive.ExtractAll(target);
                if (refused.Succeeded)
                {
                    context.Say("the second extraction should have been refused");
                    return RecipeOutcome.Failed;
                }

                context.Say("extracting again returned " + refused.ErrorCode);

                var overwriting = new ExtractionOptions();
                overwriting.Policy.Overwrite = OverwriteMode.Overwrite;
                var second = archive.ExtractAll(target, overwriting);
                if (!second.Succeeded) return Report(context, second);
                context.Say("asking for Overwrite explicitly: " + second.ErrorCode);
            }

            // Every file that went in came out byte for byte, and the empty directory survived as a directory.
            foreach (var original in Directory.GetFiles(source, "*", SearchOption.AllDirectories))
            {
                var relative = original.Substring(source.Length).TrimStart(Path.DirectorySeparatorChar);
                var produced = Path.Combine(target, relative);
                if (!File.Exists(produced))
                {
                    context.Say("missing from the output: " + relative);
                    return RecipeOutcome.Failed;
                }

                if (!RecipeContext.SameBytes(File.ReadAllBytes(original), File.ReadAllBytes(produced)))
                {
                    context.Say("differs from the input: " + relative);
                    return RecipeOutcome.Failed;
                }
            }

            if (!Directory.Exists(Path.Combine(target, "empty-folder")))
            {
                context.Say("the empty directory did not survive");
                return RecipeOutcome.Failed;
            }

            context.Say("every file matches its input, and the empty directory is still a directory");
            return RecipeOutcome.Passed;
        }

        private static RecipeOutcome Report(RecipeContext context, OperationResult result)
        {
            context.Say(result.ToString());
            return RecipeOutcome.Failed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Text
Imports Bastion.Archive
Imports Bastion.Archive.Formats.Tar

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Write and read a tar through a stream that refuses to seek — a pipe, a socket, a network response.
    ''' </summary>
    ''' <remarks>
    ''' This is the property tar has that ZIP does not. A ZIP is read from its central directory at the end, so
    ''' a reader must be able to get to the end and come back; tar is a sequence of headers each followed by
    ''' its content, so it can be produced and consumed a block at a time by something that can only go
    ''' forwards. That is why tar is what comes down a pipe, and why <c>tar | ssh</c> works at all.
    ''' <para>
    ''' The stream below refuses to seek and refuses to report a length, rather than merely not being asked to.
    ''' Writing the recipe against a <c>MemoryStream</c> would prove nothing: a writer that quietly went back to
    ''' fix a length it had already written would pass, and then fail the first time somebody used it on the
    ''' thing it exists for.
    ''' </para>
    ''' </remarks>
    Friend Module ForwardOnlyTarRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim entries = New String() {"readme.txt", "data/first.bin", "data/second.bin"}
            Dim archivePath = context.PathTo("stream.tar")

            ' Written through something that cannot seek and does not know how long it will be.
            Using file As New FileStream(archivePath, FileMode.Create, FileAccess.Write)
                Using guarded As New ForwardOnlyStream(file)
                    Using writer As New TarWriter(guarded, TarFormat.Pax, leaveOpen:=True)
                        writer.AddDirectory("data", 1577836800L, -1)
                        For Each name In entries
                            Dim content = Encoding.UTF8.GetBytes("the content of " & name & Environment.NewLine)
                            Using source As New MemoryStream(content)
                                writer.AddFile(name, source, content.Length, 1577836800L, -1)
                            End Using
                        Next
                        writer.Finish()
                    End Using
                End Using
            End Using
            context.Say("wrote {0} entries to a stream that cannot seek", entries.Length)

            ' And read back the same way: one pass, no going back.
            Dim seen = 0
            Using file As New FileStream(archivePath, FileMode.Open, FileAccess.Read)
                Using guarded As New ForwardOnlyStream(file)
                    Using reader As New TarReader(guarded, leaveOpen:=True)
                        Do While reader.MoveNext()
                            Dim entry = reader.Current
                            If entry.EntryType = TarEntryType.Directory Then
                                context.Say("  {0}/", entry.Name.TrimEnd("/"c))
                                Continue Do
                            End If
                            ' The content is read from the same forward-only stream, in place, before the
                            ' reader is asked for the next entry. There is no other order available.
                            Using produced As New MemoryStream()
                                GZipStreamUsageRecipe.CopyAll(New BoundedReader(reader, entry.Length), produced)
                                Dim text = Encoding.UTF8.GetString(produced.ToArray())
                                Dim expected = "the content of " & entry.Name & Environment.NewLine
                                If Not String.Equals(text, expected, StringComparison.Ordinal) Then
                                    context.Say("'{0}' read back as '{1}'", entry.Name, text.Trim())
                                    Return RecipeOutcome.Failed
                                End If
                                context.Say("  {0} ({1} bytes, {2:yyyy-MM-dd})", entry.Name, entry.Length, entry.ModifiedUtc)
                            End Using
                            seen += 1
                        Loop
                    End Using
                End Using
            End Using

            If seen <> entries.Length Then
                context.Say("expected {0} files and saw {1}", entries.Length, seen)
                Return RecipeOutcome.Failed
            End If
            context.Say("read {0} entries in one pass, never seeking", seen)
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>
        ''' A stream that can only go forwards, wrapped around one that could do more.
        ''' </summary>
        ''' <remarks>
        ''' Every member that would let a caller go back raises, so a reader or writer that tried would be
        ''' caught here rather than in production. This is what a pipe, a socket and an HTTP response body all
        ''' look like from the inside.
        ''' </remarks>
        Private NotInheritable Class ForwardOnlyStream
            Inherits Stream

            Private ReadOnly _inner As Stream

            Public Sub New(inner As Stream)
                If inner Is Nothing Then Throw New ArgumentNullException(NameOf(inner))
                _inner = inner
            End Sub

            Public Overrides ReadOnly Property CanRead As Boolean
                Get
                    Return _inner.CanRead
                End Get
            End Property

            Public Overrides ReadOnly Property CanWrite As Boolean
                Get
                    Return _inner.CanWrite
                End Get
            End Property

            Public Overrides ReadOnly Property CanSeek As Boolean
                Get
                    Return False
                End Get
            End Property

            Public Overrides ReadOnly Property Length As Long
                Get
                    Throw New NotSupportedException("A forward-only stream does not know its length.")
                End Get
            End Property

            Public Overrides Property Position As Long
                Get
                    Throw New NotSupportedException("A forward-only stream does not know where it is.")
                End Get
                Set(value As Long)
                    Throw New NotSupportedException("A forward-only stream cannot seek.")
                End Set
            End Property

            Public Overrides Function Seek(offset As Long, origin As SeekOrigin) As Long
                Throw New NotSupportedException("A forward-only stream cannot seek.")
            End Function

            Public Overrides Sub SetLength(value As Long)
                Throw New NotSupportedException("A forward-only stream cannot be resized.")
            End Sub

            Public Overrides Function Read(buffer() As Byte, offset As Integer, count As Integer) As Integer
                Return _inner.Read(buffer, offset, count)
            End Function

            Public Overrides Sub Write(buffer() As Byte, offset As Integer, count As Integer)
                _inner.Write(buffer, offset, count)
            End Sub

            Public Overrides Sub Flush()
                _inner.Flush()
            End Sub
        End Class

        ''' <summary>
        ''' The current entry's content as a stream that stops at the entry's length.
        ''' </summary>
        ''' <remarks>
        ''' <see cref="TarReader.Read"/> serves the current entry and stops at its end on its own; this wrapper
        ''' exists only so the content can be handed to something that takes a <see cref="Stream"/>.
        ''' </remarks>
        Private NotInheritable Class BoundedReader
            Inherits Stream

            Private ReadOnly _reader As TarReader
            Private _left As Long

            Public Sub New(reader As TarReader, length As Long)
                _reader = reader
                _left = length
            End Sub

            Public Overrides ReadOnly Property CanRead As Boolean
                Get
                    Return True
                End Get
            End Property

            Public Overrides ReadOnly Property CanSeek As Boolean
                Get
                    Return False
                End Get
            End Property

            Public Overrides ReadOnly Property CanWrite As Boolean
                Get
                    Return False
                End Get
            End Property

            Public Overrides ReadOnly Property Length As Long
                Get
                    Throw New NotSupportedException("An entry being streamed does not answer for its length here.")
                End Get
            End Property

            Public Overrides Property Position As Long
                Get
                    Throw New NotSupportedException("An entry being streamed does not know where it is.")
                End Get
                Set(value As Long)
                    Throw New NotSupportedException("An entry being streamed cannot seek.")
                End Set
            End Property

            Public Overrides Function Seek(offset As Long, origin As SeekOrigin) As Long
                Throw New NotSupportedException("An entry being streamed cannot seek.")
            End Function

            Public Overrides Sub SetLength(value As Long)
                Throw New NotSupportedException("An entry being streamed cannot be resized.")
            End Sub

            Public Overrides Sub Write(buffer() As Byte, offset As Integer, count As Integer)
                Throw New NotSupportedException("An entry being read cannot be written to.")
            End Sub

            Public Overrides Function Read(buffer() As Byte, offset As Integer, count As Integer) As Integer
                If _left <= 0L Then Return 0
                Dim wanted = CInt(Math.Min(CLng(count), _left))
                Dim taken = _reader.Read(buffer, offset, wanted)
                If taken > 0 Then _left -= CLng(taken)
                Return taken
            End Function

            Public Overrides Sub Flush()
            End Sub
        End Class

    End Module

End Namespace

C#

using System;
using System.IO;
using System.Text;
using Bastion.Archive.Formats.Tar;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Write and read a tar through a stream that refuses to seek — a pipe, a socket, a network response.
    /// </summary>
    /// <remarks>
    /// This is the property tar has that ZIP does not. A ZIP is read from its central directory at the end, so
    /// a reader must be able to get to the end and come back; tar is a sequence of headers each followed by
    /// its content, so it can be produced and consumed a block at a time by something that can only go
    /// forwards. That is why tar is what comes down a pipe, and why <c>tar | ssh</c> works at all.
    /// <para>
    /// The stream below refuses to seek and refuses to report a length, rather than merely not being asked to.
    /// Writing the recipe against a <c>MemoryStream</c> would prove nothing: a writer that quietly went back
    /// to fix a length it had already written would pass, and then fail the first time somebody used it on the
    /// thing it exists for.
    /// </para>
    /// </remarks>
    internal static class ForwardOnlyTarRecipe
    {
        /// <summary>Midnight on the first of January 2020, in Unix seconds.</summary>
        private const long FixedTime = 1577836800L;

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var entries = new[] { "readme.txt", "data/first.bin", "data/second.bin" };
            var archivePath = context.PathTo("stream.tar");

            // Written through something that cannot seek and does not know how long it will be.
            using (var file = new FileStream(archivePath, FileMode.Create, FileAccess.Write))
            using (var guarded = new ForwardOnlyStream(file))
            using (var writer = new TarWriter(guarded, TarFormat.Pax, leaveOpen: true))
            {
                writer.AddDirectory("data", FixedTime, -1);
                foreach (var name in entries)
                {
                    var content = Encoding.UTF8.GetBytes("the content of " + name + Environment.NewLine);
                    using (var source = new MemoryStream(content))
                    {
                        writer.AddFile(name, source, content.Length, FixedTime, -1);
                    }
                }

                writer.Finish();
            }

            context.Say("wrote {0} entries to a stream that cannot seek", entries.Length);

            // And read back the same way: one pass, no going back.
            var seen = 0;
            using (var file = new FileStream(archivePath, FileMode.Open, FileAccess.Read))
            using (var guarded = new ForwardOnlyStream(file))
            using (var reader = new TarReader(guarded, leaveOpen: true))
            {
                while (reader.MoveNext())
                {
                    var entry = reader.Current;
                    if (entry.EntryType == TarEntryType.Directory)
                    {
                        context.Say("  {0}/", entry.Name.TrimEnd('/'));
                        continue;
                    }

                    // The content is read from the same forward-only stream, in place, before the reader is
                    // asked for the next entry. There is no other order available.
                    using (var produced = new MemoryStream())
                    {
                        GZipStreamUsageRecipe.CopyAll(new BoundedReader(reader, entry.Length), produced);
                        var text = Encoding.UTF8.GetString(produced.ToArray());
                        var expected = "the content of " + entry.Name + Environment.NewLine;
                        if (!string.Equals(text, expected, StringComparison.Ordinal))
                        {
                            context.Say("'{0}' read back as '{1}'", entry.Name, text.Trim());
                            return RecipeOutcome.Failed;
                        }

                        context.Say("  {0} ({1} bytes, {2:yyyy-MM-dd})", entry.Name, entry.Length, entry.ModifiedUtc);
                    }

                    seen++;
                }
            }

            if (seen != entries.Length)
            {
                context.Say("expected {0} files and saw {1}", entries.Length, seen);
                return RecipeOutcome.Failed;
            }

            context.Say("read {0} entries in one pass, never seeking", seen);
            return RecipeOutcome.Passed;
        }

        /// <summary>
        /// A stream that can only go forwards, wrapped around one that could do more.
        /// </summary>
        /// <remarks>
        /// Every member that would let a caller go back raises, so a reader or writer that tried would be
        /// caught here rather than in production. This is what a pipe, a socket and an HTTP response body all
        /// look like from the inside.
        /// </remarks>
        private sealed class ForwardOnlyStream : Stream
        {
            private readonly Stream _inner;

            public ForwardOnlyStream(Stream inner)
            {
                _inner = inner ?? throw new ArgumentNullException(nameof(inner));
            }

            public override bool CanRead => _inner.CanRead;

            public override bool CanWrite => _inner.CanWrite;

            public override bool CanSeek => false;

            public override long Length =>
                throw new NotSupportedException("A forward-only stream does not know its length.");

            public override long Position
            {
                get => throw new NotSupportedException("A forward-only stream does not know where it is.");
                set => throw new NotSupportedException("A forward-only stream cannot seek.");
            }

            public override long Seek(long offset, SeekOrigin origin)
            {
                throw new NotSupportedException("A forward-only stream cannot seek.");
            }

            public override void SetLength(long value)
            {
                throw new NotSupportedException("A forward-only stream cannot be resized.");
            }

            public override int Read(byte[] buffer, int offset, int count)
            {
                return _inner.Read(buffer, offset, count);
            }

            public override void Write(byte[] buffer, int offset, int count)
            {
                _inner.Write(buffer, offset, count);
            }

            public override void Flush()
            {
                _inner.Flush();
            }
        }

        /// <summary>
        /// The current entry's content as a stream that stops at the entry's length.
        /// </summary>
        /// <remarks>
        /// <see cref="TarReader.Read"/> serves the current entry and stops at its end on its own; this wrapper
        /// exists only so the content can be handed to something that takes a <see cref="Stream"/>.
        /// </remarks>
        private sealed class BoundedReader : Stream
        {
            private readonly TarReader _reader;
            private long _left;

            public BoundedReader(TarReader reader, long length)
            {
                _reader = reader;
                _left = length;
            }

            public override bool CanRead => true;

            public override bool CanSeek => false;

            public override bool CanWrite => false;

            public override long Length =>
                throw new NotSupportedException("An entry being streamed does not answer for its length here.");

            public override long Position
            {
                get => throw new NotSupportedException("An entry being streamed does not know where it is.");
                set => throw new NotSupportedException("An entry being streamed cannot seek.");
            }

            public override long Seek(long offset, SeekOrigin origin)
            {
                throw new NotSupportedException("An entry being streamed cannot seek.");
            }

            public override void SetLength(long value)
            {
                throw new NotSupportedException("An entry being streamed cannot be resized.");
            }

            public override void Write(byte[] buffer, int offset, int count)
            {
                throw new NotSupportedException("An entry being read cannot be written to.");
            }

            public override int Read(byte[] buffer, int offset, int count)
            {
                if (_left <= 0L) return 0;
                var wanted = (int)Math.Min(count, _left);
                var taken = _reader.Read(buffer, offset, wanted);
                if (taken > 0) _left -= taken;
                return taken;
            }

            public override void Flush()
            {
            }
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Text
Imports Bastion.Archive
Imports Bastion.Archive.Formats.Zip

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Read a ZIP off a stream that cannot seek — a socket, a pipe, or a download in progress.
    ''' </summary>
    ''' <remarks>
    ''' <c>Archive.Open</c> starts at the central directory, which lives at the <em>end</em> of a ZIP, so it
    ''' needs a stream it can seek. <c>ZipStreamReader</c> walks the local file headers instead, in the order
    ''' they were written, and never looks back — which is what lets an archive be read as it arrives.
    ''' <para>
    ''' The trade is worth understanding. The central directory is where a ZIP records the truth about each
    ''' entry; a local header can disagree with it, and a forward-only reader has only the local header to go
    ''' on. Where the whole archive is in hand, <c>Archive.Open</c> remains the better reader.
    ''' </para>
    ''' </remarks>
    Friend Module ForwardOnlyZipRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("streamed.zip")

            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, "tree", Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            ' Read it back through something that refuses to seek, which is the whole point of the exercise.
            Dim entries = 0
            Dim bytes = 0L
            Using file As New FileStream(archivePath, FileMode.Open, FileAccess.Read)
                Using arriving As New ArrivingStream(file)
                    Using reader As New ZipStreamReader(arriving, leaveOpen:=True)
                        While reader.MoveNext()
                            Dim entry = reader.Current
                            If entry.IsDirectory Then Continue While
                            ' The content is read once, forwards. The reader owns this stream and finishes it
                            ' on the next MoveNext, so it is deliberately not disposed here.
                            Dim content = reader.OpenEntry()
                            Dim buffer(65535) As Byte
                            Dim taken = content.Read(buffer, 0, buffer.Length)
                            While taken > 0
                                bytes += taken
                                taken = content.Read(buffer, 0, buffer.Length)
                            End While
                            entries += 1
                        End While
                    End Using
                End Using
            End Using

            context.Say("{0} entries and {1} read forwards, off a stream that cannot seek",
                        entries, RecipeContext.Readable(bytes))
            If entries = 0 OrElse bytes = 0 Then Return RecipeOutcome.Failed
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>A stream that reads but will not seek, standing in for a socket.</summary>
        Private NotInheritable Class ArrivingStream
            Inherits Stream

            Private ReadOnly _inner As Stream

            Public Sub New(inner As Stream)
                _inner = inner
            End Sub

            Public Overrides ReadOnly Property CanRead As Boolean
                Get
                    Return True
                End Get
            End Property

            Public Overrides ReadOnly Property CanSeek As Boolean
                Get
                    Return False
                End Get
            End Property

            Public Overrides ReadOnly Property CanWrite As Boolean
                Get
                    Return False
                End Get
            End Property

            Public Overrides ReadOnly Property Length As Long
                Get
                    Throw New NotSupportedException()
                End Get
            End Property

            Public Overrides Property Position As Long
                Get
                    Throw New NotSupportedException()
                End Get
                Set(value As Long)
                    Throw New NotSupportedException()
                End Set
            End Property

            ''' <summary>Hands over a little at a time, as a network would.</summary>
            Public Overrides Function Read(buffer As Byte(), offset As Integer, count As Integer) As Integer
                Return _inner.Read(buffer, offset, Math.Min(count, 4096))
            End Function

            Public Overrides Sub Flush()
            End Sub

            Public Overrides Function Seek(offset As Long, origin As SeekOrigin) As Long
                Throw New NotSupportedException()
            End Function

            Public Overrides Sub SetLength(value As Long)
                Throw New NotSupportedException()
            End Sub

            Public Overrides Sub Write(buffer As Byte(), offset As Integer, count As Integer)
                Throw New NotSupportedException()
            End Sub
        End Class

    End Module

End Namespace

C#

using System;
using System.IO;
using Bastion.Archive.Formats.Zip;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Read a ZIP off a stream that cannot seek — a socket, a pipe, or a download in progress.
    /// </summary>
    /// <remarks>
    /// <c>Archive.Open</c> starts at the central directory, which lives at the <em>end</em> of a ZIP, so it
    /// needs a stream it can seek. <c>ZipStreamReader</c> walks the local file headers instead, in the order
    /// they were written, and never looks back — which is what lets an archive be read as it arrives.
    /// <para>
    /// The trade is worth understanding. The central directory is where a ZIP records the truth about each
    /// entry; a local header can disagree with it, and a forward-only reader has only the local header to go
    /// on. Where the whole archive is in hand, <c>Archive.Open</c> remains the better reader.
    /// </para>
    /// </remarks>
    internal static class ForwardOnlyZipRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("streamed.zip");

            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, "tree", null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return RecipeOutcome.Failed;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            // Read it back through something that refuses to seek, which is the whole point of the exercise.
            var entries = 0;
            var bytes = 0L;
            using (var file = new FileStream(archivePath, FileMode.Open, FileAccess.Read))
            using (var arriving = new ArrivingStream(file))
            using (var reader = new ZipStreamReader(arriving, leaveOpen: true))
            {
                while (reader.MoveNext())
                {
                    var entry = reader.Current;
                    if (entry.IsDirectory) continue;
                    // The content is read once, forwards. The reader owns this stream and finishes it on the
                    // next MoveNext, so it is deliberately not disposed here.
                    var content = reader.OpenEntry();
                    var buffer = new byte[65536];
                    int taken;
                    while ((taken = content.Read(buffer, 0, buffer.Length)) > 0) bytes += taken;
                    entries++;
                }
            }

            context.Say("{0} entries and {1} read forwards, off a stream that cannot seek",
                entries, RecipeContext.Readable(bytes));
            return entries == 0 || bytes == 0 ? RecipeOutcome.Failed : RecipeOutcome.Passed;
        }

        /// <summary>A stream that reads but will not seek, standing in for a socket.</summary>
        private sealed class ArrivingStream : Stream
        {
            private readonly Stream _inner;

            public ArrivingStream(Stream inner) => _inner = inner;

            public override bool CanRead => true;
            public override bool CanSeek => false;
            public override bool CanWrite => false;
            public override long Length => throw new NotSupportedException();

            public override long Position
            {
                get => throw new NotSupportedException();
                set => throw new NotSupportedException();
            }

            /// <summary>Hands over a little at a time, as a network would.</summary>
            public override int Read(byte[] buffer, int offset, int count) =>
                _inner.Read(buffer, offset, Math.Min(count, 4096));

            public override void Flush() { }
            public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();
            public override void SetLength(long value) => throw new NotSupportedException();
            public override void Write(byte[] buffer, int offset, int count) => throw new NotSupportedException();
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Text
Imports Bastion.Archive
Imports Bastion.Archive.Formats.GZip

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Compress and decompress one stream, with the header fields gzip actually carries.
    ''' </summary>
    ''' <remarks>
    ''' A <c>.gz</c> file is not an archive: it holds one stream of bytes and a little metadata about it, which
    ''' is why the name of the original file is a field in the header rather than something the format works
    ''' out. That field is the reason <c>gzip -d</c> can restore a name a download mangled.
    ''' <para>
    ''' The part worth knowing is the last one. A gzip file is **members concatenated**, which is what
    ''' <c>cat a.gz b.gz</c> produces and what every log rotation produces. A reader that stops at the first
    ''' trailer is right about almost every file it will ever meet and silently truncates the rest.
    ''' </para>
    ''' </remarks>
    Friend Module GZipStreamUsageRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim content = Encoding.UTF8.GetBytes(Repeat("the quick brown fox jumps over the lazy dog. ", 400))

            Dim compressedPath = context.PathTo("notes.txt.gz")
            Using file As New FileStream(compressedPath, FileMode.Create, FileAccess.Write)
                ' Level, the original name, and the modification time in Unix seconds.
                Using writer As New GZipEncoderStream(file, 9, "notes.txt", 1577836800L, leaveOpen:=True)
                    writer.Write(content, 0, content.Length)
                End Using
            End Using

            Dim compressed = New FileInfo(compressedPath).Length
            context.Say("{0} in, {1} out ({2:P1} of the original)",
                        RecipeContext.Readable(content.Length), RecipeContext.Readable(compressed),
                        compressed / CDbl(content.Length))

            Using file As New FileStream(compressedPath, FileMode.Open, FileAccess.Read)
                Using reader As New GZipDecoderStream(file, leaveOpen:=True)
                    Using produced As New MemoryStream()
                        CopyAll(reader, produced)
                        If Not RecipeContext.SameBytes(content, produced.ToArray()) Then
                            context.Say("the bytes that came back are not the bytes that went in")
                            Return RecipeOutcome.Failed
                        End If
                        context.Say("header says the original was called '{0}', modified {1:yyyy-MM-dd}",
                                    reader.OriginalName,
                                    New DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc).AddSeconds(reader.ModifiedUnixTime))
                    End Using
                End Using
            End Using

            ' Two members, joined the way a rotated log is joined.
            Dim joinedPath = context.PathTo("joined.gz")
            Dim first = Encoding.UTF8.GetBytes("the first member" & Environment.NewLine)
            Dim second = Encoding.UTF8.GetBytes("the second member" & Environment.NewLine)
            Using file As New FileStream(joinedPath, FileMode.Create, FileAccess.Write)
                For Each part In New Byte()() {first, second}
                    Using writer As New GZipEncoderStream(file, 6, Nothing, 0L, leaveOpen:=True)
                        writer.Write(part, 0, part.Length)
                    End Using
                Next
            End Using

            Using file As New FileStream(joinedPath, FileMode.Open, FileAccess.Read)
                Using reader As New GZipDecoderStream(file, leaveOpen:=True)
                    Using produced As New MemoryStream()
                        CopyAll(reader, produced)
                        Dim expected(first.Length + second.Length - 1) As Byte
                        System.Buffer.BlockCopy(first, 0, expected, 0, first.Length)
                        System.Buffer.BlockCopy(second, 0, expected, first.Length, second.Length)
                        If Not RecipeContext.SameBytes(expected, produced.ToArray()) Then
                            context.Say("a joined file read back short, so only the first member was read")
                            Return RecipeOutcome.Failed
                        End If
                        context.Say("two joined members read as one stream of {0} bytes; MemberCount is {1}",
                                    produced.Length, reader.MemberCount)
                        If reader.MemberCount <> 2 Then
                            context.Say("expected two members to be reported")
                            Return RecipeOutcome.Failed
                        End If
                    End Using
                End Using
            End Using

            Return RecipeOutcome.Passed
        End Function

        ''' <summary>
        ''' Copies a stream to the end. Written out rather than using <c>CopyTo</c>, which net46 does have but
        ''' which hides the one thing a decoder recipe should show: a read returning fewer bytes than asked for
        ''' is normal, and only zero means the end.
        ''' </summary>
        Friend Sub CopyAll(source As Stream, destination As Stream)
            Dim buffer(81919) As Byte
            Do
                Dim taken = source.Read(buffer, 0, buffer.Length)
                If taken <= 0 Then Exit Do
                destination.Write(buffer, 0, taken)
            Loop
        End Sub

        ''' <summary>A string repeated, without depending on which frameworks have string.Repeat.</summary>
        Friend Function Repeat(value As String, times As Integer) As String
            Dim builder As New StringBuilder(value.Length * times)
            For index = 1 To times
                builder.Append(value)
            Next
            Return builder.ToString()
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;
using System.Text;
using Bastion.Archive.Formats.GZip;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Compress and decompress one stream, with the header fields gzip actually carries.
    /// </summary>
    /// <remarks>
    /// A <c>.gz</c> file is not an archive: it holds one stream of bytes and a little metadata about it, which
    /// is why the name of the original file is a field in the header rather than something the format works
    /// out. That field is the reason <c>gzip -d</c> can restore a name a download mangled.
    /// <para>
    /// The part worth knowing is the last one. A gzip file is <b>members concatenated</b>, which is what
    /// <c>cat a.gz b.gz</c> produces and what every log rotation produces. A reader that stops at the first
    /// trailer is right about almost every file it will ever meet and silently truncates the rest.
    /// </para>
    /// </remarks>
    internal static class GZipStreamUsageRecipe
    {
        /// <summary>Midnight on the first of January 2020, in Unix seconds.</summary>
        private const long FixedTime = 1577836800L;

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var content = Encoding.UTF8.GetBytes(Repeat("the quick brown fox jumps over the lazy dog. ", 400));

            var compressedPath = context.PathTo("notes.txt.gz");
            using (var file = new FileStream(compressedPath, FileMode.Create, FileAccess.Write))
            {
                // Level, the original name, and the modification time in Unix seconds.
                using (var writer = new GZipEncoderStream(file, 9, "notes.txt", FixedTime, leaveOpen: true))
                {
                    writer.Write(content, 0, content.Length);
                }
            }

            var compressed = new FileInfo(compressedPath).Length;
            context.Say("{0} in, {1} out ({2:P1} of the original)",
                RecipeContext.Readable(content.Length), RecipeContext.Readable(compressed),
                compressed / (double)content.Length);

            using (var file = new FileStream(compressedPath, FileMode.Open, FileAccess.Read))
            using (var reader = new GZipDecoderStream(file, leaveOpen: true))
            using (var produced = new MemoryStream())
            {
                CopyAll(reader, produced);
                if (!RecipeContext.SameBytes(content, produced.ToArray()))
                {
                    context.Say("the bytes that came back are not the bytes that went in");
                    return RecipeOutcome.Failed;
                }

                context.Say("header says the original was called '{0}', modified {1:yyyy-MM-dd}",
                    reader.OriginalName,
                    new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc).AddSeconds(reader.ModifiedUnixTime));
            }

            // Two members, joined the way a rotated log is joined.
            var joinedPath = context.PathTo("joined.gz");
            var first = Encoding.UTF8.GetBytes("the first member" + Environment.NewLine);
            var second = Encoding.UTF8.GetBytes("the second member" + Environment.NewLine);
            using (var file = new FileStream(joinedPath, FileMode.Create, FileAccess.Write))
            {
                foreach (var part in new[] { first, second })
                {
                    using (var writer = new GZipEncoderStream(file, 6, null, 0L, leaveOpen: true))
                    {
                        writer.Write(part, 0, part.Length);
                    }
                }
            }

            using (var file = new FileStream(joinedPath, FileMode.Open, FileAccess.Read))
            using (var reader = new GZipDecoderStream(file, leaveOpen: true))
            using (var produced = new MemoryStream())
            {
                CopyAll(reader, produced);
                var expected = new byte[first.Length + second.Length];
                Buffer.BlockCopy(first, 0, expected, 0, first.Length);
                Buffer.BlockCopy(second, 0, expected, first.Length, second.Length);
                if (!RecipeContext.SameBytes(expected, produced.ToArray()))
                {
                    context.Say("a joined file read back short, so only the first member was read");
                    return RecipeOutcome.Failed;
                }

                context.Say("two joined members read as one stream of {0} bytes; MemberCount is {1}",
                    produced.Length, reader.MemberCount);
                if (reader.MemberCount != 2)
                {
                    context.Say("expected two members to be reported");
                    return RecipeOutcome.Failed;
                }
            }

            return RecipeOutcome.Passed;
        }

        /// <summary>
        /// Copies a stream to the end. Written out rather than using <c>CopyTo</c>, which net46 does have but
        /// which hides the one thing a decoder recipe should show: a read returning fewer bytes than asked for
        /// is normal, and only zero means the end.
        /// </summary>
        internal static void CopyAll(Stream source, Stream destination)
        {
            var buffer = new byte[81920];
            while (true)
            {
                var taken = source.Read(buffer, 0, buffer.Length);
                if (taken <= 0) break;
                destination.Write(buffer, 0, taken);
            }
        }

        /// <summary>A string repeated, without depending on which frameworks have string.Repeat.</summary>
        internal static string Repeat(string value, int times)
        {
            var builder = new StringBuilder(value.Length * times);
            for (var index = 0; index < times; index++)
            {
                builder.Append(value);
            }

            return builder.ToString();
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Globalization
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' List an archive the way <c>7z l -slt</c> does.
    ''' </summary>
    ''' <remarks>
    ''' Listing reads the central directory only, so it is fast and it never touches entry data — which is also
    ''' why the listing of an encrypted archive is complete while its contents stay unreadable.
    ''' Three properties on the archive itself are worth a look and are missing from most libraries:
    ''' <c>EmbeddedStubSize</c> is non-zero for a self-extracting archive, <c>TrailingDataSize</c> counts bytes
    ''' after the end record that were ignored, and the warnings on the open result say what was odd about the
    ''' file rather than leaving you to guess.
    ''' </remarks>
    Friend Module ListEntriesRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("listing.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, Nothing, Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return RecipeOutcome.Failed
                End If
                writer.Comment = "A listing sample."
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                context.Say("format {0}, {1} entries, {2} volume(s), stub {3} bytes, trailing {4} bytes",
                            archive.Format, archive.Entries.Count, archive.VolumeCount,
                            archive.EmbeddedStubSize, archive.TrailingDataSize)
                If archive.Comment.Length > 0 Then context.Say("comment: " & archive.Comment)
                For Each warning In opened.Warnings
                    context.Say("warning {0}: {1}", warning.Code, warning.Message)
                Next

                context.Say("  {0}  {1}  {2}  {3}  {4}  {5}",
                            "size".PadLeft(9), "packed".PadLeft(9), "ratio".PadLeft(6),
                            "method".PadRight(8), "modified (UTC)".PadRight(19), "name")
                For Each entry In archive.Entries
                    Dim ratio = If(entry.Size > 0, 100.0 * entry.CompressedSize / entry.Size, 0.0)
                    context.Say("  {0}  {1}  {2}  {3}  {4}  {5}{6}",
                                entry.Size.ToString("N0", CultureInfo.CurrentCulture).PadLeft(9),
                                entry.CompressedSize.ToString("N0", CultureInfo.CurrentCulture).PadLeft(9),
                                ratio.ToString("N1", CultureInfo.CurrentCulture).PadLeft(5) & "%",
                                entry.Method.ToString().PadRight(8),
                                entry.LastWriteUtc.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture),
                                entry.Name,
                                Detail(entry))
                Next

                ' A listing is only worth printing if the facts in it are facts.
                For Each entry In archive.Entries
                    If entry.IsDirectory Then Continue For
                    If entry.Size < 0 OrElse entry.CompressedSize < 0 Then Return RecipeOutcome.Failed
                    If entry.Crc32 < 0 Then Return RecipeOutcome.Failed
                    If entry.LastWriteUtc = DateTime.MinValue Then Return RecipeOutcome.Failed
                Next
            End Using
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>The parts of an entry worth saying only when they are true of it.</summary>
        Private Function Detail(entry As ArchiveEntry) As String
            Dim parts = ""
            If entry.IsDirectory Then parts &= "  (directory)"
            If entry.IsEncrypted Then parts &= "  (" & entry.Encryption.ToString() & ")"
            If entry.IsSymbolicLink Then parts &= "  (symbolic link)"
            If Not entry.IsDirectory Then
                parts &= String.Format(CultureInfo.InvariantCulture, "  crc={0:X8}", entry.Crc32)
            End If
            Return parts
        End Function

    End Module

End Namespace

C#

using System;
using System.Globalization;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// List an archive the way <c>7z l -slt</c> does.
    /// </summary>
    /// <remarks>
    /// Listing reads the central directory only, so it is fast and it never touches entry data — which is also
    /// why the listing of an encrypted archive is complete while its contents stay unreadable.
    /// Three properties on the archive itself are worth a look and are missing from most libraries:
    /// <c>EmbeddedStubSize</c> is non-zero for a self-extracting archive, <c>TrailingDataSize</c> counts bytes
    /// after the end record that were ignored, and the warnings on the open result say what was odd about the
    /// file rather than leaving you to guess.
    /// </remarks>
    internal static class ListEntriesRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("listing.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, null, null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return RecipeOutcome.Failed;
                }

                writer.Comment = "A listing sample.";
                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                context.Say("format {0}, {1} entries, {2} volume(s), stub {3} bytes, trailing {4} bytes",
                    archive.Format, archive.Entries.Count, archive.VolumeCount,
                    archive.EmbeddedStubSize, archive.TrailingDataSize);
                if (archive.Comment.Length > 0) context.Say("comment: " + archive.Comment);
                foreach (var warning in opened.Warnings)
                {
                    context.Say("warning {0}: {1}", warning.Code, warning.Message);
                }

                context.Say("  {0}  {1}  {2}  {3}  {4}  {5}",
                    "size".PadLeft(9), "packed".PadLeft(9), "ratio".PadLeft(6),
                    "method".PadRight(8), "modified (UTC)".PadRight(19), "name");
                foreach (var entry in archive.Entries)
                {
                    var ratio = entry.Size > 0 ? 100.0 * entry.CompressedSize / entry.Size : 0.0;
                    context.Say("  {0}  {1}  {2}  {3}  {4}  {5}{6}",
                        entry.Size.ToString("N0", CultureInfo.CurrentCulture).PadLeft(9),
                        entry.CompressedSize.ToString("N0", CultureInfo.CurrentCulture).PadLeft(9),
                        ratio.ToString("N1", CultureInfo.CurrentCulture).PadLeft(5) + "%",
                        entry.Method.ToString().PadRight(8),
                        entry.LastWriteUtc.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture),
                        entry.Name,
                        Detail(entry));
                }

                // A listing is only worth printing if the facts in it are facts.
                foreach (var entry in archive.Entries)
                {
                    if (entry.IsDirectory) continue;
                    if (entry.Size < 0 || entry.CompressedSize < 0) return RecipeOutcome.Failed;
                    if (entry.Crc32 < 0) return RecipeOutcome.Failed;
                    if (entry.LastWriteUtc == DateTime.MinValue) return RecipeOutcome.Failed;
                }
            }

            return RecipeOutcome.Passed;
        }

        /// <summary>The parts of an entry worth saying only when they are true of it.</summary>
        private static string Detail(ArchiveEntry entry)
        {
            var parts = "";
            if (entry.IsDirectory) parts += "  (directory)";
            if (entry.IsEncrypted) parts += "  (" + entry.Encryption + ")";
            if (entry.IsSymbolicLink) parts += "  (symbolic link)";
            if (!entry.IsDirectory)
            {
                parts += string.Format(CultureInfo.InvariantCulture, "  crc={0:X8}", entry.Crc32);
            }

            return parts;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Globalization
Imports System.IO
Imports System.Text
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Pass 65 535 entries, which needs the Zip64 end record.
    ''' </summary>
    ''' <remarks>
    ''' The end-of-central-directory record holds the entry count in 16 bits, so 65 535 is as far as the
    ''' original layout reaches. Past that the archive needs the Zip64 end record and its locator, and — the
    ''' same trap as the sizes — <c>0xFFFF</c> is a reserved redirection rather than a count, so exactly 65 535
    ''' entries needs Zip64 as well.
    ''' This recipe writes seventy thousand entries to put the count genuinely over the line. It is also the
    ''' recipe that shows memory is decoupled from entry count: writing and then listing seventy
    ''' thousand entries streams, and the process does not grow with the archive.
    ''' </remarks>
    Friend Module ManyEntriesRecipe

        ''' <summary>Comfortably past the 16-bit limit, and past the 0xFFFF sentinel.</summary>
        Private Const EntryCount As Integer = 70000

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim archivePath = context.PathTo("many.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If

            context.Say("writing {0:N0} entries", EntryCount)
            Dim payload = Encoding.ASCII.GetBytes("one small entry among seventy thousand")
            Using writer = started.Writer
                For index = 0 To EntryCount - 1
                    ' Foldered names, so the archive also exercises a directory tree a browser has to build.
                    Dim name = String.Format(CultureInfo.InvariantCulture, "bucket-{0:D3}/entry-{1:D5}.txt",
                                             index Mod 100, index)
                    Using source As New MemoryStream(payload, False)
                        Dim added = writer.AddStream(source, name, Nothing)
                        If Not added.Succeeded Then
                            context.Say(added.ToString())
                            Return RecipeOutcome.Failed
                        End If
                    End Using
                Next
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
                context.Say("wrote {0:N0} entries in {1:N1} s, archive {2}",
                            writer.EntryCount, finished.Elapsed.TotalSeconds,
                            RecipeContext.Readable(New FileInfo(archivePath).Length))
            End Using

            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                context.Say("read back {0:N0} entries in {1:N1} s",
                            archive.Entries.Count, opened.Elapsed.TotalSeconds)
                If archive.Entries.Count <> EntryCount Then
                    context.Say("the entry count did not survive the round trip")
                    Return RecipeOutcome.Failed
                End If
                ' The first and the last, because an off-by-one in the directory shows up at the ends.
                context.Say("first: {0}", archive.Entries(0).Name)
                context.Say("last:  {0}", archive.Entries(archive.Entries.Count - 1).Name)
                If Not String.Equals(archive.Entries(0).Name, "bucket-000/entry-00000.txt", StringComparison.Ordinal) Then
                    Return RecipeOutcome.Failed
                End If
                If Not String.Equals(archive.Entries(archive.Entries.Count - 1).Name, "bucket-099/entry-69999.txt",
                                     StringComparison.Ordinal) Then
                    Return RecipeOutcome.Failed
                End If

                ' Extracting seventy thousand files would take longer than it proves; one is enough to show the
                ' directory offsets are right, and Test below reads every one of them.
                Dim chosen = archive.Entries(EntryCount \ 2)
                Using buffer As New MemoryStream()
                    Dim streamed = archive.ExtractToStream(chosen, buffer, Nothing)
                    If Not streamed.Succeeded Then
                        context.Say(streamed.ToString())
                        Return RecipeOutcome.Failed
                    End If
                    If buffer.Length <> payload.Length Then Return RecipeOutcome.Failed
                    context.Say("entry {0:N0} of the set read back {1} bytes", EntryCount \ 2, buffer.Length)
                End Using

                Dim tested = archive.Test(Nothing)
                If Not tested.Succeeded Then
                    context.Say(tested.ToString())
                    Return RecipeOutcome.Failed
                End If
                context.Say("every entry verified in {0:N1} s", tested.Elapsed.TotalSeconds)
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.Globalization;
using System.IO;
using System.Text;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Pass 65 535 entries, which needs the Zip64 end record.
    /// </summary>
    /// <remarks>
    /// The end-of-central-directory record holds the entry count in 16 bits, so 65 535 is as far as the
    /// original layout reaches. Past that the archive needs the Zip64 end record and its locator, and — the
    /// same trap as the sizes — <c>0xFFFF</c> is a reserved redirection rather than a count, so exactly 65 535
    /// entries needs Zip64 as well.
    /// This recipe writes seventy thousand entries to put the count genuinely over the line. It is also the
    /// recipe that shows memory is decoupled from entry count: writing and then listing seventy
    /// thousand entries streams, and the process does not grow with the archive.
    /// </remarks>
    internal static class ManyEntriesRecipe
    {
        /// <summary>Comfortably past the 16-bit limit, and past the 0xFFFF sentinel.</summary>
        private const int EntryCount = 70000;

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var archivePath = context.PathTo("many.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say("writing {0:N0} entries", EntryCount);
            var payload = Encoding.ASCII.GetBytes("one small entry among seventy thousand");
            using (var writer = started.Writer)
            {
                for (var index = 0; index < EntryCount; index++)
                {
                    // Foldered names, so the archive also exercises a directory tree a browser has to build.
                    var name = string.Format(CultureInfo.InvariantCulture, "bucket-{0:D3}/entry-{1:D5}.txt",
                        index % 100, index);
                    using (var source = new MemoryStream(payload, false))
                    {
                        var added = writer.AddStream(source, name, null);
                        if (!added.Succeeded)
                        {
                            context.Say(added.ToString());
                            return RecipeOutcome.Failed;
                        }
                    }
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }

                context.Say("wrote {0:N0} entries in {1:N1} s, archive {2}",
                    writer.EntryCount, finished.Elapsed.TotalSeconds,
                    RecipeContext.Readable(new FileInfo(archivePath).Length));
            }

            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                context.Say("read back {0:N0} entries in {1:N1} s", archive.Entries.Count, opened.Elapsed.TotalSeconds);
                if (archive.Entries.Count != EntryCount)
                {
                    context.Say("the entry count did not survive the round trip");
                    return RecipeOutcome.Failed;
                }

                // The first and the last, because an off-by-one in the directory shows up at the ends.
                context.Say("first: {0}", archive.Entries[0].Name);
                context.Say("last:  {0}", archive.Entries[archive.Entries.Count - 1].Name);
                if (!string.Equals(archive.Entries[0].Name, "bucket-000/entry-00000.txt", StringComparison.Ordinal))
                {
                    return RecipeOutcome.Failed;
                }

                if (!string.Equals(archive.Entries[archive.Entries.Count - 1].Name, "bucket-099/entry-69999.txt",
                        StringComparison.Ordinal))
                {
                    return RecipeOutcome.Failed;
                }

                // Extracting seventy thousand files would take longer than it proves; one is enough to show the
                // directory offsets are right, and Test below reads every one of them.
                var chosen = archive.Entries[EntryCount / 2];
                using (var buffer = new MemoryStream())
                {
                    var streamed = archive.ExtractToStream(chosen, buffer, null);
                    if (!streamed.Succeeded)
                    {
                        context.Say(streamed.ToString());
                        return RecipeOutcome.Failed;
                    }

                    if (buffer.Length != payload.Length) return RecipeOutcome.Failed;
                    context.Say("entry {0:N0} of the set read back {1} bytes", EntryCount / 2, buffer.Length);
                }

                var tested = archive.Test(null);
                if (!tested.Succeeded)
                {
                    context.Say(tested.ToString());
                    return RecipeOutcome.Failed;
                }

                context.Say("every entry verified in {0:N1} s", tested.Elapsed.TotalSeconds);
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Security

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Keep a download's Mark of the Web on what comes out of it, so Windows still treats those files as from the internet.
    ''' </summary>
    ''' <remarks>
    ''' A browser marks a download with a <c>Zone.Identifier</c> stream; SmartScreen and Office's Protected View read it.
    ''' An archive tool that drops the mark on extraction launders every file inside, which is how malware has slipped past
    ''' both. <see cref="ExtractionPolicy.PropagateMarkOfTheWeb"/> copies the archive's mark onto every file extracted. It
    ''' needs Windows and NTFS; elsewhere the recipe says so and skips.
    ''' </remarks>
    Friend Module MarkOfTheWebRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            If Environment.OSVersion.Platform <> PlatformID.Win32NT Then
                context.Say("the Mark of the Web is an NTFS stream, so this needs Windows")
                Return RecipeOutcome.Skipped
            End If
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("downloaded.zip")
            Using writer = ArchiveWriter.Create(archivePath, Nothing).Writer
                If Not writer.AddDirectory(source, Nothing, Nothing).Succeeded OrElse Not writer.Complete().Succeeded Then Return RecipeOutcome.Failed
            End Using

            ' What a browser writes on a download; the \\?\ form reaches the stream on .NET Framework too.
            Dim mark = "[ZoneTransfer]" & Environment.NewLine & "ZoneId=3" & Environment.NewLine & "HostUrl=https://example.com/downloaded.zip" & Environment.NewLine
            Try
                File.WriteAllText(StreamPath(archivePath), mark)
            Catch ex As IOException
                context.Say("this volume cannot hold alternate streams ({0}), so there is no mark to keep", ex.Message)
                Return RecipeOutcome.Skipped
            End Try
            context.Say("the archive is marked as downloaded (zone 3, the internet)")

            For Each propagate In New Boolean() {False, True}
                Dim target = context.PathTo(If(propagate, "kept", "laundered"))
                Using opened = Archive.Open(archivePath).Archive
                    Dim options As New ExtractionOptions()
                    options.Policy.PropagateMarkOfTheWeb = propagate
                    If Not opened.ExtractAll(target, options).Succeeded Then Return RecipeOutcome.Failed
                End Using
                Dim extracted = StreamPath(Path.Combine(target, "readme.txt"))
                Dim carried = File.Exists(extracted) AndAlso File.ReadAllText(extracted).Contains("ZoneId=3")
                context.Say("PropagateMarkOfTheWeb = {0}: readme.txt {1}", propagate, If(carried, "carries the mark", "has no mark"))
                If carried <> propagate Then Return RecipeOutcome.Failed
            Next
            Return RecipeOutcome.Passed
        End Function

        Private Function StreamPath(filePath As String) As String
            Return "\\?\" & Path.GetFullPath(filePath) & ":Zone.Identifier"
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;
using Bastion.Archive.Security;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Keep a download's Mark of the Web on what comes out of it, so Windows still treats those files as from the internet.
    /// </summary>
    /// <remarks>
    /// A browser marks a download with a <c>Zone.Identifier</c> stream; SmartScreen and Office's Protected View read it.
    /// An archive tool that drops the mark on extraction launders every file inside, which is how malware has slipped past
    /// both. <see cref="ExtractionPolicy.PropagateMarkOfTheWeb"/> copies the archive's mark onto every file extracted. It
    /// needs Windows and NTFS; elsewhere the recipe says so and skips.
    /// </remarks>
    internal static class MarkOfTheWebRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            if (Environment.OSVersion.Platform != PlatformID.Win32NT)
            {
                context.Say("the Mark of the Web is an NTFS stream, so this needs Windows");
                return RecipeOutcome.Skipped;
            }

            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("downloaded.zip");
            using (var writer = ArchiveWriter.Create(archivePath, null).Writer)
            {
                if (!writer.AddDirectory(source, null, null).Succeeded || !writer.Complete().Succeeded) return RecipeOutcome.Failed;
            }

            // What a browser writes on a download; the \\?\ form reaches the stream on .NET Framework too.
            var mark = "[ZoneTransfer]" + Environment.NewLine + "ZoneId=3" + Environment.NewLine + "HostUrl=https://example.com/downloaded.zip" + Environment.NewLine;
            try
            {
                File.WriteAllText(StreamPath(archivePath), mark);
            }
            catch (IOException ex)
            {
                context.Say("this volume cannot hold alternate streams ({0}), so there is no mark to keep", ex.Message);
                return RecipeOutcome.Skipped;
            }

            context.Say("the archive is marked as downloaded (zone 3, the internet)");

            foreach (var propagate in new[] { false, true })
            {
                var target = context.PathTo(propagate ? "kept" : "laundered");
                using (var archive = Archive.Open(archivePath).Archive)
                {
                    var options = new ExtractionOptions();
                    options.Policy.PropagateMarkOfTheWeb = propagate;
                    if (!archive.ExtractAll(target, options).Succeeded) return RecipeOutcome.Failed;
                }

                var extracted = StreamPath(Path.Combine(target, "readme.txt"));
                var carried = File.Exists(extracted) && File.ReadAllText(extracted).Contains("ZoneId=3");
                context.Say("PropagateMarkOfTheWeb = {0}: readme.txt {1}", propagate ? "True" : "False", carried ? "carries the mark" : "has no mark");
                if (carried != propagate) return RecipeOutcome.Failed;
            }

            return RecipeOutcome.Passed;
        }

        private static string StreamPath(string filePath) => @"\\?\" + Path.GetFullPath(filePath) + ":Zone.Identifier";
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Text
Imports Bastion.Archive
Imports Bastion.Archive.FileSystem

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Build content in memory, zip it, and unzip it into memory again, touching disk only for the archive.
    ''' </summary>
    ''' <remarks>
    ''' A <see cref="MemoryFolder"/> is a folder like any other, so it can be copied into an archive and an archive
    ''' can be copied into it. Changes to an archive are rebuilds; <see cref="ArchiveFolder.BeginUpdate"/> and
    ''' <see cref="ArchiveFolder.EndUpdate"/> gather several into one.
    ''' </remarks>
    Friend Module MemoryFolderRoundTripRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim memory As New MemoryFolder()
            For Each name In New String() {"a.txt", "b.txt", "notes/c.txt"}
                Dim opened = memory.GetFile(name).OpenWrite(False)
                If Not opened.Succeeded Then Return RecipeOutcome.Failed
                Dim bytes = Encoding.UTF8.GetBytes("content of " & name)
                Using stream = opened.Stream
                    stream.Write(bytes, 0, bytes.Length)
                End Using
            Next

            Dim archive As New ArchiveFolder(New DiskFile(context.PathTo("memory.zip")))
            If Not memory.CopyFilesTo(archive, Nothing).Succeeded Then Return RecipeOutcome.Failed

            ' Two changes, one rebuild.
            archive.BeginUpdate()
            If Not archive.GetFile("a.txt").Delete().Succeeded Then Return RecipeOutcome.Failed
            If Not archive.GetFolder("empty").Create().Succeeded Then Return RecipeOutcome.Failed
            Dim ended = archive.EndUpdate()
            If Not ended.Succeeded Then
                context.Say(ended.ToString())
                Return RecipeOutcome.Failed
            End If

            Dim back As New MemoryFolder()
            If Not archive.CopyFilesTo(back, Nothing).Succeeded Then Return RecipeOutcome.Failed
            Dim listed = back.GetItems(True)
            If Not listed.Succeeded Then Return RecipeOutcome.Failed
            For Each item In listed.Items
                context.Say("  {0}{1}", item.FullName, If(TypeOf item Is AbstractFolder, "/", ""))
            Next
            If back.GetFile("a.txt").Exists OrElse Not back.GetFile("notes/c.txt").Exists Then Return RecipeOutcome.Failed
            context.Say("round trip through memory.zip with one update applied")
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System.Text;
using Bastion.Archive.FileSystem;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Build content in memory, zip it, and unzip it into memory again, touching disk only for the archive.
    /// </summary>
    /// <remarks>
    /// A <see cref="MemoryFolder"/> is a folder like any other, so it can be copied into an archive and an archive
    /// can be copied into it. Changes to an archive are rebuilds; <see cref="ArchiveFolder.BeginUpdate"/> and
    /// <see cref="ArchiveFolder.EndUpdate()"/> gather several into one.
    /// </remarks>
    internal static class MemoryFolderRoundTripRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var memory = new MemoryFolder();
            foreach (var name in new[] { "a.txt", "b.txt", "notes/c.txt" })
            {
                var opened = memory.GetFile(name).OpenWrite(false);
                if (!opened.Succeeded) return RecipeOutcome.Failed;
                var bytes = Encoding.UTF8.GetBytes("content of " + name);
                using (var stream = opened.Stream)
                {
                    stream.Write(bytes, 0, bytes.Length);
                }
            }

            var archive = new ArchiveFolder(new DiskFile(context.PathTo("memory.zip")));
            if (!memory.CopyFilesTo(archive, null).Succeeded) return RecipeOutcome.Failed;

            // Two changes, one rebuild.
            archive.BeginUpdate();
            if (!archive.GetFile("a.txt").Delete().Succeeded) return RecipeOutcome.Failed;
            if (!archive.GetFolder("empty").Create().Succeeded) return RecipeOutcome.Failed;
            var ended = archive.EndUpdate();
            if (!ended.Succeeded)
            {
                context.Say(ended.ToString());
                return RecipeOutcome.Failed;
            }

            var back = new MemoryFolder();
            if (!archive.CopyFilesTo(back, null).Succeeded) return RecipeOutcome.Failed;
            var listed = back.GetItems(true);
            if (!listed.Succeeded) return RecipeOutcome.Failed;
            foreach (var item in listed.Items)
            {
                context.Say("  {0}{1}", item.FullName, item is AbstractFolder ? "/" : "");
            }

            if (back.GetFile("a.txt").Exists || !back.GetFile("notes/c.txt").Exists) return RecipeOutcome.Failed;
            context.Say("round trip through memory.zip with one update applied");
            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Write and read WinZip AES-256, and be refused without the password.
    ''' </summary>
    ''' <remarks>
    ''' WinZip AES is the only strong encryption the ZIP format has: PBKDF2-HMAC-SHA1 over a fresh random salt,
    ''' AES in counter mode, and an HMAC-SHA1-80 authentication code checked before any plaintext is handed over.
    ''' The two-byte password verifier means a wrong password is usually reported as <c>PasswordInvalid</c>
    ''' straight away rather than after decoding a gigabyte.
    ''' Two properties of the format are worth knowing before choosing it. Entry <em>names</em> are never
    ''' encrypted — an observer sees what is in the archive, only not its contents — and the iteration count is
    ''' fixed at 1000 by the specification, which is low by any modern standard and cannot be raised without
    ''' making the archive unreadable to everyone else. For new archives where interoperability is not required,
    ''' 7z encryption is the better choice; AES-256 here is for reading and writing what the world already uses.
    ''' The password itself is never logged, never put in a message and never written to a result (no credentials in any diagnostic).
    ''' </remarks>
    Friend Module PasswordAes256Recipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Const password As String = "Correct Horse Battery Staple"
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("secret.zip")

            Dim settings As New CompressionSettings() With {
                .Encryption = EncryptionMethod.Aes256,
                .Password = password
            }
            Dim started = ArchiveWriter.Create(archivePath, settings)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, Nothing, Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
                ' Anything about the archive a third-party reader may not like is reported, not hidden.
                For Each warning In writer.InteropWarnings
                    context.Say("interoperability: {0} — {1}", warning.Feature, warning.AffectedReaders)
                Next
            End Using

            ' Without the password the directory still reads: names and sizes are not encrypted by this format.
            Dim blind = Archive.Open(archivePath)
            If Not blind.Succeeded Then
                context.Say(blind.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = blind.Archive
                Dim encrypted = 0
                For Each entry In archive.Entries
                    If entry.IsDirectory Then Continue For
                    If Not entry.IsEncrypted OrElse entry.Encryption <> EncryptionMethod.Aes256 Then
                        context.Say("entry '" & entry.Name & "' is not AES-256 encrypted")
                        Return RecipeOutcome.Failed
                    End If
                    encrypted += 1
                Next
                context.Say("{0} encrypted entries are listed without the password", encrypted)
                Dim refused = archive.ExtractAll(context.PathTo("out-blind"))
                If refused.Succeeded Then
                    context.Say("extraction without the password should have been refused")
                    Return RecipeOutcome.Failed
                End If
                context.Say("extracting without it returned " & refused.ErrorCode.ToString())
                If refused.ErrorCode <> ErrorCode.PasswordRequired Then Return RecipeOutcome.Failed
            End Using

            ' A wrong password is caught by the verifier, before any data is produced.
            Dim wrong = Archive.Open(archivePath, New ArchiveOpenOptions() With {.Password = "not the password"})
            If Not wrong.Succeeded Then
                context.Say(wrong.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = wrong.Archive
                Dim rejected = archive.Test(Nothing)
                If rejected.Succeeded Then
                    context.Say("a wrong password should not have passed the test")
                    Return RecipeOutcome.Failed
                End If
                context.Say("a wrong password returned " & rejected.ErrorCode.ToString())
            End Using

            Dim opened = Archive.Open(archivePath, New ArchiveOpenOptions() With {.Password = password})
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim target = context.PathTo("out")
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim recovered = File.ReadAllBytes(Path.Combine(target, "readme.txt"))
                Dim expected = File.ReadAllBytes(Path.Combine(source, "readme.txt"))
                If Not RecipeContext.SameBytes(expected, recovered) Then
                    context.Say("the decrypted bytes do not match the input")
                    Return RecipeOutcome.Failed
                End If
                context.Say("decrypted and verified: readme.txt matches its input exactly")
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Write and read WinZip AES-256, and be refused without the password.
    /// </summary>
    /// <remarks>
    /// WinZip AES is the only strong encryption the ZIP format has: PBKDF2-HMAC-SHA1 over a fresh random salt,
    /// AES in counter mode, and an HMAC-SHA1-80 authentication code checked before any plaintext is handed over.
    /// The two-byte password verifier means a wrong password is usually reported as <c>PasswordInvalid</c>
    /// straight away rather than after decoding a gigabyte.
    /// Two properties of the format are worth knowing before choosing it. Entry <em>names</em> are never
    /// encrypted — an observer sees what is in the archive, only not its contents — and the iteration count is
    /// fixed at 1000 by the specification, which is low by any modern standard and cannot be raised without
    /// making the archive unreadable to everyone else. For new archives where interoperability is not required,
    /// 7z encryption is the better choice; AES-256 here is for reading and writing what the world already uses.
    /// The password itself is never logged, never put in a message and never written to a result (no credentials in any diagnostic).
    /// </remarks>
    internal static class PasswordAes256Recipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            const string password = "Correct Horse Battery Staple";
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("secret.zip");

            var settings = new CompressionSettings
            {
                Encryption = EncryptionMethod.Aes256,
                Password = password
            };
            var started = ArchiveWriter.Create(archivePath, settings);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, null, null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return RecipeOutcome.Failed;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }

                // Anything about the archive a third-party reader may not like is reported, not hidden.
                foreach (var warning in writer.InteropWarnings)
                {
                    context.Say("interoperability: {0} — {1}", warning.Feature, warning.AffectedReaders);
                }
            }

            // Without the password the directory still reads: names and sizes are not encrypted by this format.
            var blind = Archive.Open(archivePath);
            if (!blind.Succeeded)
            {
                context.Say(blind.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = blind.Archive)
            {
                var encrypted = 0;
                foreach (var entry in archive.Entries)
                {
                    if (entry.IsDirectory) continue;
                    if (!entry.IsEncrypted || entry.Encryption != EncryptionMethod.Aes256)
                    {
                        context.Say("entry '" + entry.Name + "' is not AES-256 encrypted");
                        return RecipeOutcome.Failed;
                    }

                    encrypted++;
                }

                context.Say("{0} encrypted entries are listed without the password", encrypted);
                var refused = archive.ExtractAll(context.PathTo("out-blind"));
                if (refused.Succeeded)
                {
                    context.Say("extraction without the password should have been refused");
                    return RecipeOutcome.Failed;
                }

                context.Say("extracting without it returned " + refused.ErrorCode);
                if (refused.ErrorCode != ErrorCode.PasswordRequired) return RecipeOutcome.Failed;
            }

            // A wrong password is caught by the verifier, before any data is produced.
            var wrong = Archive.Open(archivePath, new ArchiveOpenOptions { Password = "not the password" });
            if (!wrong.Succeeded)
            {
                context.Say(wrong.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = wrong.Archive)
            {
                var rejected = archive.Test(null);
                if (rejected.Succeeded)
                {
                    context.Say("a wrong password should not have passed the test");
                    return RecipeOutcome.Failed;
                }

                context.Say("a wrong password returned " + rejected.ErrorCode);
            }

            var opened = Archive.Open(archivePath, new ArchiveOpenOptions { Password = password });
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var target = context.PathTo("out");
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                var recovered = File.ReadAllBytes(Path.Combine(target, "readme.txt"));
                var expected = File.ReadAllBytes(Path.Combine(source, "readme.txt"));
                if (!RecipeContext.SameBytes(expected, recovered))
                {
                    context.Say("the decrypted bytes do not match the input");
                    return RecipeOutcome.Failed;
                }

                context.Say("decrypted and verified: readme.txt matches its input exactly");
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Read a traditionally encrypted archive — the old ZIP encryption, which you will meet and should not
    ''' write.
    ''' </summary>
    ''' <remarks>
    ''' Traditional PKWARE encryption is what every ZIP tool has implemented since 1990, and it was broken in
    ''' 1994: a known-plaintext attack recovers the key stream from a few bytes a reader can often guess. So
    ''' this recipe exists for the archives that already exist. Writing it is a deliberate choice the library
    ''' makes you spell out — <c>EncryptionMethod.ZipCrypto</c> carries an <c>Obsolete</c> attribute, so using
    ''' it is a compile-time warning, and the writer reports it as an interoperability warning as well.
    ''' Two details of the format show up here. The twelve-byte encryption header ends in a **check byte**, and
    ''' a wrong password fails that check better than 255 times in 256 — so a wrong password is usually reported
    ''' at once, and occasionally only when the entry's CRC fails at the end. And because the check byte has to
    ''' be chosen before the data is read, an entry written this way always carries its sizes in a data
    ''' descriptor after the data rather than in its local header.
    ''' The password is never logged, never put in a message and never written to a result.
    ''' </remarks>
    Friend Module PasswordZipCryptoReadRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Const password As String = "the old way"
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("legacy.zip")

            ' Deliberate, and deliberately noisy: the enum member is obsolete, so this is the one place in the
            ' cookbook that silences a compiler warning, and it says why.
#Disable Warning BC40000
            Dim settings As New CompressionSettings() With {
                .Encryption = EncryptionMethod.ZipCrypto,
                .Password = password
            }
#Enable Warning BC40000
            Dim started = ArchiveWriter.Create(archivePath, settings)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Dim warnedAboutStrength = False
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, Nothing, Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
                For Each warning In writer.InteropWarnings
                    context.Say("interoperability: {0} — {1}", warning.Feature, warning.AffectedReaders)
                    If warning.Feature.IndexOf("Traditional", StringComparison.Ordinal) >= 0 Then warnedAboutStrength = True
                Next
            End Using
            If Not warnedAboutStrength Then
                context.Say("the writer should have warned that traditional encryption is broken")
                Return RecipeOutcome.Failed
            End If

            ' The entry names are in the clear, as they are with AES: only the contents are encrypted.
            Dim listed = Archive.Open(archivePath)
            If Not listed.Succeeded Then
                context.Say(listed.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = listed.Archive
                Dim encrypted = 0
                For Each entry In archive.Entries
                    If entry.IsDirectory Then Continue For
                    If Not entry.IsEncrypted Then
                        context.Say("entry '" & entry.Name & "' is not encrypted")
                        Return RecipeOutcome.Failed
                    End If
                    encrypted += 1
                Next
                context.Say("{0} encrypted entries listed without the password", encrypted)
            End Using

            ' A wrong password is caught by the check byte in the encryption header, not by decoding everything.
            Dim wrong = Archive.Open(archivePath, New ArchiveOpenOptions() With {.Password = "the wrong way"})
            If Not wrong.Succeeded Then
                context.Say(wrong.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = wrong.Archive
                Dim rejected = archive.Test(Nothing)
                If rejected.Succeeded Then
                    context.Say("a wrong password should not have passed the test")
                    Return RecipeOutcome.Failed
                End If
                context.Say("a wrong password returned {0}", rejected.ErrorCode)
            End Using

            Dim opened = Archive.Open(archivePath, New ArchiveOpenOptions() With {.Password = password})
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim target = context.PathTo("out")
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim expected = File.ReadAllBytes(Path.Combine(source, "readme.txt"))
                Dim recovered = File.ReadAllBytes(Path.Combine(target, "readme.txt"))
                If Not RecipeContext.SameBytes(expected, recovered) Then
                    context.Say("the decrypted bytes do not match the input")
                    Return RecipeOutcome.Failed
                End If
                context.Say("decrypted and verified: readme.txt matches its input exactly")
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Read a traditionally encrypted archive — the old ZIP encryption, which you will meet and should not
    /// write.
    /// </summary>
    /// <remarks>
    /// Traditional PKWARE encryption is what every ZIP tool has implemented since 1990, and it was broken in
    /// 1994: a known-plaintext attack recovers the key stream from a few bytes a reader can often guess. So
    /// this recipe exists for the archives that already exist. Writing it is a deliberate choice the library
    /// makes you spell out — <c>EncryptionMethod.ZipCrypto</c> carries an <c>Obsolete</c> attribute, so using
    /// it is a compile-time warning, and the writer reports it as an interoperability warning as well.
    /// Two details of the format show up here. The twelve-byte encryption header ends in a <em>check byte</em>,
    /// and a wrong password fails that check better than 255 times in 256 — so a wrong password is usually
    /// reported at once, and occasionally only when the entry's CRC fails at the end. And because the check
    /// byte has to be chosen before the data is read, an entry written this way always carries its sizes in a
    /// data descriptor after the data rather than in its local header.
    /// The password is never logged, never put in a message and never written to a result.
    /// </remarks>
    internal static class PasswordZipCryptoReadRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            const string password = "the old way";
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("legacy.zip");

            // Deliberate, and deliberately noisy: the enum member is obsolete, so this is the one place in the
            // cookbook that silences a compiler warning, and it says why.
#pragma warning disable CS0618
            var settings = new CompressionSettings
            {
                Encryption = EncryptionMethod.ZipCrypto,
                Password = password
            };
#pragma warning restore CS0618
            var started = ArchiveWriter.Create(archivePath, settings);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            var warnedAboutStrength = false;
            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, null, null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return RecipeOutcome.Failed;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }

                foreach (var warning in writer.InteropWarnings)
                {
                    context.Say("interoperability: {0} — {1}", warning.Feature, warning.AffectedReaders);
                    if (warning.Feature.IndexOf("Traditional", StringComparison.Ordinal) >= 0)
                    {
                        warnedAboutStrength = true;
                    }
                }
            }

            if (!warnedAboutStrength)
            {
                context.Say("the writer should have warned that traditional encryption is broken");
                return RecipeOutcome.Failed;
            }

            // The entry names are in the clear, as they are with AES: only the contents are encrypted.
            var listed = Archive.Open(archivePath);
            if (!listed.Succeeded)
            {
                context.Say(listed.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = listed.Archive)
            {
                var encrypted = 0;
                foreach (var entry in archive.Entries)
                {
                    if (entry.IsDirectory)
                    {
                        continue;
                    }

                    if (!entry.IsEncrypted)
                    {
                        context.Say("entry '" + entry.Name + "' is not encrypted");
                        return RecipeOutcome.Failed;
                    }

                    encrypted++;
                }

                context.Say("{0} encrypted entries listed without the password", encrypted);
            }

            // A wrong password is caught by the check byte in the encryption header, not by decoding everything.
            var wrong = Archive.Open(archivePath, new ArchiveOpenOptions { Password = "the wrong way" });
            if (!wrong.Succeeded)
            {
                context.Say(wrong.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = wrong.Archive)
            {
                var rejected = archive.Test(null);
                if (rejected.Succeeded)
                {
                    context.Say("a wrong password should not have passed the test");
                    return RecipeOutcome.Failed;
                }

                context.Say("a wrong password returned {0}", rejected.ErrorCode);
            }

            var opened = Archive.Open(archivePath, new ArchiveOpenOptions { Password = password });
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var target = context.PathTo("out");
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                var expected = File.ReadAllBytes(Path.Combine(source, "readme.txt"));
                var recovered = File.ReadAllBytes(Path.Combine(target, "readme.txt"));
                if (!RecipeContext.SameBytes(expected, recovered))
                {
                    context.Say("the decrypted bytes do not match the input");
                    return RecipeOutcome.Failed;
                }

                context.Say("decrypted and verified: readme.txt matches its input exactly");
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Threading
Imports Bastion.Archive
Imports Bastion.Archive.Diagnostics

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Watch an operation's progress, and stop it part way through without leaving anything broken behind.
    ''' </summary>
    ''' <remarks>
    ''' Progress reports totals as well as the current entry, so a bar can be drawn from the first event. Cancelling
    ''' is a token on the monitor: the operation stops at the next entry boundary, the result says
    ''' <see cref="ErrorCode.Cancelled"/>, and — because every file is written through a temporary one swapped
    ''' into place — the destination holds only whole files. In a UI, make the monitor on the UI thread and its
    ''' events arrive there too.
    ''' </remarks>
    Friend Module ProgressAndCancelRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.PathTo("many")
            Directory.CreateDirectory(source)
            For index = 0 To 39
                File.WriteAllBytes(Path.Combine(source, $"file{index:00}.bin"), RecipeContext.PseudoRandom(20000, index + 1))
            Next
            Dim archivePath = context.PathTo("many.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            Using writer = started.Writer
                If Not writer.AddDirectory(source, Nothing, Nothing).Succeeded OrElse Not writer.Complete().Succeeded Then Return RecipeOutcome.Failed
            End Using

            Using cancellation As New CancellationTokenSource()
                Dim monitor As New OperationMonitor(Nothing) With {.CancellationToken = cancellation.Token, .ProgressInterval = TimeSpan.Zero}
                Dim lastShown = -1
                AddHandler monitor.Progress,
                    Sub(sender, e)
                        Dim percent = CInt(Math.Floor(e.TotalPercent / 25.0)) * 25
                        If percent <> lastShown Then
                            lastShown = percent
                            context.Say("  {0}% — {1} of {2} items", percent, e.ProcessedItems, e.TotalItems)
                        End If
                    End Sub
                AddHandler monitor.EntryCompleted,
                    Sub(sender, e)
                        ' Stop after the tenth file, as a user pressing Cancel would.
                        If e.EntryIndex = 9 Then cancellation.Cancel()
                    End Sub

                Dim opened = Archive.Open(archivePath, New ArchiveOpenOptions() With {.Monitor = monitor})
                If Not opened.Succeeded Then Return RecipeOutcome.Failed
                Dim target = context.PathTo("partial")
                Using archive = opened.Archive
                    Dim result = archive.ExtractAll(target)
                    context.Say("the extraction ended with {0}", result.ErrorCode)
                    If result.ErrorCode <> ErrorCode.Cancelled Then Return RecipeOutcome.Failed
                End Using
                Dim written = Directory.GetFiles(target)
                For Each file In written
                    If New FileInfo(file).Length <> 20000 Then
                        context.Say("found a partial file: {0}", file)
                        Return RecipeOutcome.Failed
                    End If
                Next
                context.Say("{0} whole files written before the stop, and nothing half-written", written.Length)
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;
using System.Threading;
using Bastion.Archive.Diagnostics;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Watch an operation's progress, and stop it part way through without leaving anything broken behind.
    /// </summary>
    /// <remarks>
    /// Progress reports totals as well as the current entry, so a bar can be drawn from the first event. Cancelling
    /// is a token on the monitor: the operation stops at the next entry boundary, the result says
    /// <see cref="ErrorCode.Cancelled"/>, and — because every file is written through a temporary one swapped
    /// into place — the destination holds only whole files. In a UI, make the monitor on the UI thread and its
    /// events arrive there too.
    /// </remarks>
    internal static class ProgressAndCancelRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.PathTo("many");
            Directory.CreateDirectory(source);
            for (var index = 0; index <= 39; index++)
            {
                File.WriteAllBytes(Path.Combine(source, $"file{index:00}.bin"), RecipeContext.PseudoRandom(20000, index + 1));
            }

            var archivePath = context.PathTo("many.zip");
            var started = ArchiveWriter.Create(archivePath);
            using (var writer = started.Writer)
            {
                if (!writer.AddDirectory(source, null, null).Succeeded || !writer.Complete().Succeeded) return RecipeOutcome.Failed;
            }

            using (var cancellation = new CancellationTokenSource())
            {
                var monitor = new OperationMonitor(null) { CancellationToken = cancellation.Token, ProgressInterval = TimeSpan.Zero };
                var lastShown = -1;
                monitor.Progress += (sender, e) =>
                {
                    var percent = (int)Math.Floor(e.TotalPercent / 25.0) * 25;
                    if (percent != lastShown)
                    {
                        lastShown = percent;
                        context.Say("  {0}% — {1} of {2} items", percent, e.ProcessedItems, e.TotalItems);
                    }
                };
                monitor.EntryCompleted += (sender, e) =>
                {
                    // Stop after the tenth file, as a user pressing Cancel would.
                    if (e.EntryIndex == 9) cancellation.Cancel();
                };

                var opened = Archive.Open(archivePath, new ArchiveOpenOptions { Monitor = monitor });
                if (!opened.Succeeded) return RecipeOutcome.Failed;
                var target = context.PathTo("partial");
                using (var archive = opened.Archive)
                {
                    var result = archive.ExtractAll(target);
                    context.Say("the extraction ended with {0}", result.ErrorCode);
                    if (result.ErrorCode != ErrorCode.Cancelled) return RecipeOutcome.Failed;
                }

                var written = Directory.GetFiles(target);
                foreach (var file in written)
                {
                    if (new FileInfo(file).Length != 20000)
                    {
                        context.Say("found a partial file: {0}", file);
                        return RecipeOutcome.Failed;
                    }
                }

                context.Say("{0} whole files written before the stop, and nothing half-written", written.Length);
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Write a <c>.7z</c> and read it back, which is the same two calls as a ZIP.
    ''' </summary>
    ''' <remarks>
    ''' The point of this recipe is how little there is to it. The format is chosen by the name — a path
    ''' ending <c>.7z</c> writes 7z and anything else writes ZIP — so a caller who has learnt one format has
    ''' learnt both, and switching an application from one to the other is a change of file extension rather
    ''' than a change of API. Set <see cref="CompressionSettings.Format"/> when there is no name to
    ''' read, which is the case for the stream overloads.
    ''' <para>
    ''' What you get by default is what <c>7z a</c> gives: LZMA2, one solid block, and every entry's type
    ''' inspected so that executable code gets a branch filter and text does not.
    ''' </para>
    ''' </remarks>
    Friend Module SevenZipCreateRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("books.7z")

            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, "books", Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
                context.Say("wrote {0} entries as {1}", writer.EntryCount,
                            RecipeContext.Readable(New FileInfo(archivePath).Length))
            End Using

            ' Opening is the same call as for a ZIP: the format comes from the archive's own signature rather
            ' than from its name, so an archive misnamed .zip still opens as what it actually is.
            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                context.Say("opened as {0} with {1} entries", archive.Format, archive.Entries.Count)
                Dim target = context.PathTo("unpacked")
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                If Not SameTree(source, Path.Combine(target, "books"), context) Then Return RecipeOutcome.Failed
            End Using

            context.Say("every file came back with the same bytes")
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>Compares two trees file by file, which is the only check worth making here.</summary>
        Friend Function SameTree(expected As String, actual As String, context As RecipeContext) As Boolean
            For Each original In Directory.GetFiles(expected, "*", SearchOption.AllDirectories)
                Dim relative = original.Substring(expected.Length).TrimStart(Path.DirectorySeparatorChar)
                Dim produced = Path.Combine(actual, relative)
                If Not File.Exists(produced) Then
                    context.Say("missing after extraction: {0}", relative)
                    Return False
                End If
                If Not RecipeContext.SameBytes(File.ReadAllBytes(original), File.ReadAllBytes(produced)) Then
                    context.Say("different after extraction: {0}", relative)
                    Return False
                End If
            Next
            Return True
        End Function

    End Module

End Namespace

C#

using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Write a <c>.7z</c> and read it back, which is the same two calls as a ZIP.
    /// </summary>
    /// <remarks>
    /// The point of this recipe is how little there is to it. The format is chosen by the name — a path
    /// ending <c>.7z</c> writes 7z and anything else writes ZIP — so a caller who has learnt one format has
    /// learnt both, and switching an application from one to the other is a change of file extension rather
    /// than a change of API. Set <see cref="CompressionSettings.Format"/> when there is no name to
    /// read, which is the case for the stream overloads.
    /// <para>
    /// What you get by default is what <c>7z a</c> gives: LZMA2, one solid block, and every entry's type
    /// inspected so that executable code gets a branch filter and text does not.
    /// </para>
    /// </remarks>
    internal static class SevenZipCreateRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("books.7z");

            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, "books", null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return RecipeOutcome.Failed;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }

                context.Say("wrote {0} entries as {1}", writer.EntryCount,
                    RecipeContext.Readable(new FileInfo(archivePath).Length));
            }

            // Opening is the same call as for a ZIP: the format comes from the archive's own signature rather
            // than from its name, so an archive misnamed .zip still opens as what it actually is.
            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                context.Say("opened as {0} with {1} entries", archive.Format, archive.Entries.Count);
                var target = context.PathTo("unpacked");
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                if (!SameTree(source, Path.Combine(target, "books"), context))
                {
                    return RecipeOutcome.Failed;
                }
            }

            context.Say("every file came back with the same bytes");
            return RecipeOutcome.Passed;
        }

        /// <summary>Compares two trees file by file, which is the only check worth making here.</summary>
        internal static bool SameTree(string expected, string actual, RecipeContext context)
        {
            foreach (var original in Directory.GetFiles(expected, "*", SearchOption.AllDirectories))
            {
                var relative = original.Substring(expected.Length).TrimStart(Path.DirectorySeparatorChar);
                var produced = Path.Combine(actual, relative);
                if (!File.Exists(produced))
                {
                    context.Say("missing after extraction: {0}", relative);
                    return false;
                }

                if (!RecipeContext.SameBytes(File.ReadAllBytes(original), File.ReadAllBytes(produced)))
                {
                    context.Say("different after extraction: {0}", relative);
                    return false;
                }
            }

            return true;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Encrypt a 7z with AES-256, and then encrypt its header so the names go too.
    ''' </summary>
    ''' <remarks>
    ''' This is the one place 7z is plainly better than ZIP. A password-protected ZIP hides the *contents* of
    ''' its entries and publishes their **names, sizes and structure** to anyone who opens it — the central
    ''' directory has to stay readable for the archive to be an archive. 7z can encrypt the header too, and
    ''' then an archive without the password is a wall: no names, no sizes, no count.
    ''' <para>
    ''' Both use AES-256 over a key derived from the password, so the strength is the password's. The recipe
    ''' shows the refusal as well as the success, because an encrypted archive that opens without the
    ''' password is not encrypted, and that is worth proving rather than assuming.
    ''' </para>
    ''' </remarks>
    Friend Module SevenZipEncryptionRecipe

        Private Const Password As String = "correct horse battery staple"

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()

            If Not Write(context, source, "content-only.7z", encryptHeader:=False) Then Return RecipeOutcome.Failed
            If Not Write(context, source, "names-too.7z", encryptHeader:=True) Then Return RecipeOutcome.Failed

            ' With the content encrypted but the header in the clear, the names are readable by anyone.
            Dim listed = Archive.Open(context.PathTo("content-only.7z"))
            If Not listed.Succeeded Then
                context.Say(listed.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = listed.Archive
                context.Say("without the password, content-only.7z still lists {0} entries, first '{1}'",
                            archive.Entries.Count, archive.Entries(0).Name)
            End Using

            ' With the header encrypted there is nothing to list without the password.
            Dim blind = Archive.Open(context.PathTo("names-too.7z"))
            If blind.Succeeded Then
                Using blind.Archive
                End Using
                context.Say("names-too.7z listed without a password, which defeats the point of -mhe")
                Return RecipeOutcome.Failed
            End If
            context.Say("without the password, names-too.7z does not open at all: {0}", blind.ErrorCode)

            ' And with it, everything comes back.
            Dim options As New ArchiveOpenOptions()
            options.Password = Password
            Dim opened = Archive.Open(context.PathTo("names-too.7z"), options)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim target = context.PathTo("unpacked")
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                If Not SevenZipCreateRecipe.SameTree(source, Path.Combine(target, "books"), context) Then
                    Return RecipeOutcome.Failed
                End If
            End Using
            context.Say("with the password, every file came back with the same bytes")
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>Writes one encrypted archive.</summary>
        Private Function Write(context As RecipeContext, source As String, name As String,
                               encryptHeader As Boolean) As Boolean
            Dim settings As New CompressionSettings()
            settings.Password = Password
            settings.EncryptHeaders = encryptHeader
            settings.Level = 5

            Dim started = ArchiveWriter.Create(context.PathTo(name), settings)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return False
            End If
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, "books", Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return False
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return False
                End If
            End Using
            context.Say("wrote {0} ({1})", name,
                        If(encryptHeader, "content and names encrypted", "content encrypted, names readable"))
            Return True
        End Function

    End Module

End Namespace

C#

using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Encrypt a 7z with AES-256, and then encrypt its header so the names go too.
    /// </summary>
    /// <remarks>
    /// This is the one place 7z is plainly better than ZIP. A password-protected ZIP hides the <i>contents</i>
    /// of its entries and publishes their <b>names, sizes and structure</b> to anyone who opens it — the
    /// central directory has to stay readable for the archive to be an archive. 7z can encrypt the header
    /// too, and then an archive without the password is a wall: no names, no sizes, no count.
    /// <para>
    /// Both use AES-256 over a key derived from the password, so the strength is the password's. The recipe
    /// shows the refusal as well as the success, because an encrypted archive that opens without the password
    /// is not encrypted, and that is worth proving rather than assuming.
    /// </para>
    /// </remarks>
    internal static class SevenZipEncryptionRecipe
    {
        private const string Password = "correct horse battery staple";

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();

            if (!Write(context, source, "content-only.7z", encryptHeader: false))
            {
                return RecipeOutcome.Failed;
            }

            if (!Write(context, source, "names-too.7z", encryptHeader: true))
            {
                return RecipeOutcome.Failed;
            }

            // With the content encrypted but the header in the clear, the names are readable by anyone.
            var listed = Archive.Open(context.PathTo("content-only.7z"));
            if (!listed.Succeeded)
            {
                context.Say(listed.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = listed.Archive)
            {
                context.Say("without the password, content-only.7z still lists {0} entries, first '{1}'",
                    archive.Entries.Count, archive.Entries[0].Name);
            }

            // With the header encrypted there is nothing to list without the password.
            var blind = Archive.Open(context.PathTo("names-too.7z"));
            if (blind.Succeeded)
            {
                blind.Archive.Dispose();
                context.Say("names-too.7z listed without a password, which defeats the point of -mhe");
                return RecipeOutcome.Failed;
            }

            context.Say("without the password, names-too.7z does not open at all: {0}", blind.ErrorCode);

            // And with it, everything comes back.
            var options = new ArchiveOpenOptions { Password = Password };
            var opened = Archive.Open(context.PathTo("names-too.7z"), options);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var target = context.PathTo("unpacked");
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                if (!SevenZipCreateRecipe.SameTree(source, Path.Combine(target, "books"), context))
                {
                    return RecipeOutcome.Failed;
                }
            }

            context.Say("with the password, every file came back with the same bytes");
            return RecipeOutcome.Passed;
        }

        /// <summary>Writes one encrypted archive.</summary>
        private static bool Write(RecipeContext context, string source, string name, bool encryptHeader)
        {
            var settings = new CompressionSettings
            {
                Password = Password,
                EncryptHeaders = encryptHeader,
                Level = 5
            };

            var started = ArchiveWriter.Create(context.PathTo(name), settings);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return false;
            }

            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, "books", null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return false;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return false;
                }
            }

            context.Say("wrote {0} ({1})", name,
                encryptHeader ? "content and names encrypted" : "content encrypted, names readable");
            return true;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Collections.Generic
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Write the same files with each of 7z's six coders, and see what each one costs.
    ''' </summary>
    ''' <remarks>
    ''' 7z carries six: Copy, Deflate, BZip2, LZMA, LZMA2 and PPMd. LZMA2 is the default and the right answer
    ''' almost always — it is LZMA with a framing that lets it be split across threads. The two worth knowing
    ''' about are the ends of the range: **Copy** stores, which is what you want for data that is already
    ''' compressed, and **PPMd** models text far better than anything else here, at a cost in memory and
    ''' speed that only text repays.
    ''' <para>
    ''' A method the format has no coder for — Deflate64, Xz, Zstandard, all of which this library writes in
    ''' other formats — is **refused by name** rather than quietly replaced. A caller who asked for Zstandard
    ''' and silently received LZMA2 would have an archive that works and settings that lie about it.
    ''' </para>
    ''' </remarks>
    Friend Module SevenZipMethodsRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim sizes As New List(Of String)()

            For Each method In New CompressionMethod() {CompressionMethod.Store, CompressionMethod.Deflate,
                                                        CompressionMethod.BZip2, CompressionMethod.Lzma,
                                                        CompressionMethod.Lzma2, CompressionMethod.Ppmd}
                Dim archivePath = context.PathTo("by-" & method.ToString().ToLowerInvariant() & ".7z")
                Dim settings As New CompressionSettings()
                settings.Method = method
                ' Store is the one method that must be asked for at level 0; a compressing level with Copy is
                ' a contradiction the writer refuses rather than resolves.
                settings.Level = If(method = CompressionMethod.Store, 0, 5)

                Dim started = ArchiveWriter.Create(archivePath, settings)
                If Not started.Succeeded Then
                    context.Say(started.ToString())
                    Return RecipeOutcome.Failed
                End If
                Using writer = started.Writer
                    Dim added = writer.AddDirectory(source, "books", Nothing)
                    If Not added.Succeeded Then
                        context.Say(added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                    Dim finished = writer.Complete()
                    If Not finished.Succeeded Then
                        context.Say(finished.ToString())
                        Return RecipeOutcome.Failed
                    End If
                End Using

                Dim length = New FileInfo(archivePath).Length
                sizes.Add(method.ToString() & " " & RecipeContext.Readable(length))
                context.Say("{0,-8} {1}", method, RecipeContext.Readable(length))

                If Not ReadsBack(archivePath, source, context) Then Return RecipeOutcome.Failed
            Next

            ' The refusal is part of the contract, so it is shown rather than described.
            Dim refusedSettings As New CompressionSettings()
            refusedSettings.Method = CompressionMethod.Zstd
            Dim refused = ArchiveWriter.Create(context.PathTo("impossible.7z"), refusedSettings)
            If refused.Succeeded Then
                Using refused.Writer
                End Using
                context.Say("expected Zstandard in a 7z to be refused, and it was not")
                Return RecipeOutcome.Failed
            End If
            context.Say("asking for Zstandard in a 7z is refused: {0}", refused.ErrorDescription)

            Return RecipeOutcome.Passed
        End Function

        ''' <summary>Opens an archive and checks every file survived the round trip.</summary>
        Private Function ReadsBack(archivePath As String, source As String, context As RecipeContext) As Boolean
            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return False
            End If
            Using archive = opened.Archive
                Dim target = archivePath & ".out"
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return False
                End If
                Return SevenZipCreateRecipe.SameTree(source, Path.Combine(target, "books"), context)
            End Using
        End Function

    End Module

End Namespace

C#

using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Write the same files with each of 7z's six coders, and see what each one costs.
    /// </summary>
    /// <remarks>
    /// 7z carries six: Copy, Deflate, BZip2, LZMA, LZMA2 and PPMd. LZMA2 is the default and the right answer
    /// almost always — it is LZMA with a framing that lets it be split across threads. The two worth knowing
    /// about are the ends of the range: <b>Copy</b> stores, which is what you want for data that is already
    /// compressed, and <b>PPMd</b> models text far better than anything else here, at a cost in memory and
    /// speed that only text repays.
    /// <para>
    /// A method the format has no coder for — Deflate64, Xz, Zstandard, all of which this library writes in
    /// other formats — is <b>refused by name</b> rather than quietly replaced. A caller who asked for
    /// Zstandard and silently received LZMA2 would have an archive that works and settings that lie about it.
    /// </para>
    /// </remarks>
    internal static class SevenZipMethodsRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();

            var methods = new[]
            {
                CompressionMethod.Store, CompressionMethod.Deflate, CompressionMethod.BZip2,
                CompressionMethod.Lzma, CompressionMethod.Lzma2, CompressionMethod.Ppmd
            };

            foreach (var method in methods)
            {
                var archivePath = context.PathTo("by-" + method.ToString().ToLowerInvariant() + ".7z");
                var settings = new CompressionSettings
                {
                    Method = method,
                    // Store is the one method that must be asked for at level 0; a compressing level with
                    // Copy is a contradiction the writer refuses rather than resolves.
                    Level = method == CompressionMethod.Store ? 0 : 5
                };

                var started = ArchiveWriter.Create(archivePath, settings);
                if (!started.Succeeded)
                {
                    context.Say(started.ToString());
                    return RecipeOutcome.Failed;
                }

                using (var writer = started.Writer)
                {
                    var added = writer.AddDirectory(source, "books", null);
                    if (!added.Succeeded)
                    {
                        context.Say(added.ToString());
                        return RecipeOutcome.Failed;
                    }

                    var finished = writer.Complete();
                    if (!finished.Succeeded)
                    {
                        context.Say(finished.ToString());
                        return RecipeOutcome.Failed;
                    }
                }

                context.Say("{0,-8} {1}", method, RecipeContext.Readable(new FileInfo(archivePath).Length));
                if (!ReadsBack(archivePath, source, context))
                {
                    return RecipeOutcome.Failed;
                }
            }

            // The refusal is part of the contract, so it is shown rather than described.
            var refusedSettings = new CompressionSettings { Method = CompressionMethod.Zstd };
            var refused = ArchiveWriter.Create(context.PathTo("impossible.7z"), refusedSettings);
            if (refused.Succeeded)
            {
                refused.Writer.Dispose();
                context.Say("expected Zstandard in a 7z to be refused, and it was not");
                return RecipeOutcome.Failed;
            }

            context.Say("asking for Zstandard in a 7z is refused: {0}", refused.ErrorDescription);
            return RecipeOutcome.Passed;
        }

        /// <summary>Opens an archive and checks every file survived the round trip.</summary>
        private static bool ReadsBack(string archivePath, string source, RecipeContext context)
        {
            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return false;
            }

            using (var archive = opened.Archive)
            {
                var target = archivePath + ".out";
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return false;
                }

                return SevenZipCreateRecipe.SameTree(source, Path.Combine(target, "books"), context);
            }
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Solid or not: the trade 7z makes that ZIP cannot, and what it costs either way.
    ''' </summary>
    ''' <remarks>
    ''' A ZIP compresses every entry on its own, so any entry can be read without touching the others and
    ''' nothing learns from what came before. 7z compresses entries together in a **folder** — a run of
    ''' entries treated as one stream — so a hundred similar files compress against each other and the
    ''' archive is far smaller.
    ''' <para>
    ''' The price is paid on reading. Reaching the fiftieth entry of a solid folder means decoding the
    ''' forty-nine before it, because there is no index into the middle of an LZMA stream. That is fine for
    ''' an archive read from front to back, and wrong for one a program dips into. <c>SolidMode.NonSolid</c>
    ''' puts each entry in a folder of its own and buys back the random access.
    ''' </para>
    ''' <para>
    ''' The numbers this prints are the argument. Nothing here is a rule of thumb: run it on your own data.
    ''' </para>
    ''' </remarks>
    Friend Module SevenZipSolidRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()

            Dim solidBytes = 0L
            Dim looseBytes = 0L

            For Each mode In New SolidMode() {SolidMode.Automatic, SolidMode.NonSolid}
                Dim archivePath = context.PathTo(If(mode = SolidMode.NonSolid, "loose.7z", "solid.7z"))
                Dim settings As New CompressionSettings()
                settings.Solid = mode
                settings.Level = 5

                Dim started = ArchiveWriter.Create(archivePath, settings)
                If Not started.Succeeded Then
                    context.Say(started.ToString())
                    Return RecipeOutcome.Failed
                End If
                Using writer = started.Writer
                    Dim added = writer.AddDirectory(source, "books", Nothing)
                    If Not added.Succeeded Then
                        context.Say(added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                    Dim finished = writer.Complete()
                    If Not finished.Succeeded Then
                        context.Say(finished.ToString())
                        Return RecipeOutcome.Failed
                    End If
                End Using

                Dim length = New FileInfo(archivePath).Length
                If mode = SolidMode.NonSolid Then looseBytes = length Else solidBytes = length
                context.Say("{0,-10} {1}", mode, RecipeContext.Readable(length))

                Dim opened = Archive.Open(archivePath)
                If Not opened.Succeeded Then
                    context.Say(opened.ToString())
                    Return RecipeOutcome.Failed
                End If
                Using archive = opened.Archive
                    Dim target = archivePath & ".out"
                    Dim extracted = archive.ExtractAll(target)
                    If Not extracted.Succeeded Then
                        context.Say(extracted.ToString())
                        Return RecipeOutcome.Failed
                    End If
                    If Not SevenZipCreateRecipe.SameTree(source, Path.Combine(target, "books"), context) Then
                        Return RecipeOutcome.Failed
                    End If
                End Using
            Next

            If solidBytes > 0L AndAlso looseBytes > 0L Then
                context.Say("solid is {0:0.0}% the size of one-folder-per-entry, and the cost is that reaching",
                            100.0R * solidBytes / looseBytes)
                context.Say("any entry means decoding the ones before it in its folder")
            End If
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Solid or not: the trade 7z makes that ZIP cannot, and what it costs either way.
    /// </summary>
    /// <remarks>
    /// A ZIP compresses every entry on its own, so any entry can be read without touching the others and
    /// nothing learns from what came before. 7z compresses entries together in a <b>folder</b> — a run of
    /// entries treated as one stream — so a hundred similar files compress against each other and the
    /// archive is far smaller.
    /// <para>
    /// The price is paid on reading. Reaching the fiftieth entry of a solid folder means decoding the
    /// forty-nine before it, because there is no index into the middle of an LZMA stream. That is fine for an
    /// archive read from front to back, and wrong for one a program dips into. <c>SolidMode.NonSolid</c> puts
    /// each entry in a folder of its own and buys back the random access.
    /// </para>
    /// <para>
    /// The numbers this prints are the argument. Nothing here is a rule of thumb: run it on your own data.
    /// </para>
    /// </remarks>
    internal static class SevenZipSolidRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            long solidBytes = 0;
            long looseBytes = 0;

            foreach (var mode in new[] { SolidMode.Automatic, SolidMode.NonSolid })
            {
                var archivePath = context.PathTo(mode == SolidMode.NonSolid ? "loose.7z" : "solid.7z");
                var settings = new CompressionSettings { Solid = mode, Level = 5 };

                var started = ArchiveWriter.Create(archivePath, settings);
                if (!started.Succeeded)
                {
                    context.Say(started.ToString());
                    return RecipeOutcome.Failed;
                }

                using (var writer = started.Writer)
                {
                    var added = writer.AddDirectory(source, "books", null);
                    if (!added.Succeeded)
                    {
                        context.Say(added.ToString());
                        return RecipeOutcome.Failed;
                    }

                    var finished = writer.Complete();
                    if (!finished.Succeeded)
                    {
                        context.Say(finished.ToString());
                        return RecipeOutcome.Failed;
                    }
                }

                var length = new FileInfo(archivePath).Length;
                if (mode == SolidMode.NonSolid)
                {
                    looseBytes = length;
                }
                else
                {
                    solidBytes = length;
                }

                context.Say("{0,-10} {1}", mode, RecipeContext.Readable(length));

                var opened = Archive.Open(archivePath);
                if (!opened.Succeeded)
                {
                    context.Say(opened.ToString());
                    return RecipeOutcome.Failed;
                }

                using (var archive = opened.Archive)
                {
                    var target = archivePath + ".out";
                    var extracted = archive.ExtractAll(target);
                    if (!extracted.Succeeded)
                    {
                        context.Say(extracted.ToString());
                        return RecipeOutcome.Failed;
                    }

                    if (!SevenZipCreateRecipe.SameTree(source, Path.Combine(target, "books"), context))
                    {
                        return RecipeOutcome.Failed;
                    }
                }
            }

            if (solidBytes > 0 && looseBytes > 0)
            {
                context.Say("solid is {0:0.0}% the size of one-folder-per-entry, and the cost is that reaching",
                    100.0 * solidBytes / looseBytes);
                context.Say("any entry means decoding the ones before it in its folder");
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Collections.Generic
Imports System.IO
Imports System.Linq
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Remove, rename and add inside a <c>.7z</c> — the same <see cref="ArchiveUpdate"/> calls as for a ZIP.
    ''' </summary>
    ''' <remarks>
    ''' The difference is underneath, and worth knowing. A ZIP update carries untouched entries across still
    ''' compressed; a 7z one cannot, because a solid 7z compresses its entries together and taking one out
    ''' changes the bytes of everything after it. So a 7z update decodes what it keeps and writes it again,
    ''' with the settings you pass governing the whole result — and the settings' password is also what opens
    ''' the source if it is encrypted. Like every update, it writes a new file and never touches the original.
    ''' </remarks>
    Friend Module SevenZipUpdateRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("books.7z")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                If Not writer.AddDirectory(source, Nothing, Nothing).Succeeded OrElse Not writer.Complete().Succeeded Then
                    context.Say("the starting archive could not be written")
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim cover = context.PathTo("cover.txt")
            File.WriteAllText(cover, "a cover added by the update")
            Dim update As New ArchiveUpdate(archivePath)
            update.Remove("data.bin")
            update.Rename("readme.txt", "docs/readme.txt")
            update.AddOrReplaceFile(cover, "cover.txt")
            Dim updatedPath = context.PathTo("books-updated.7z")
            Dim result = update.Apply(updatedPath, Nothing)
            If Not result.Succeeded Then
                context.Say(result.ToString())
                Return RecipeOutcome.Failed
            End If

            Dim opened = Archive.Open(updatedPath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim names As New List(Of String)()
                For Each entry In archive.Entries
                    If Not entry.IsDirectory Then names.Add(entry.Name)
                Next
                names.Sort(StringComparer.Ordinal)
                context.Say("the updated archive holds {0}", String.Join(", ", names))
                Dim wanted = New String() {"cover.txt", "docs/readme.txt", "documents/notes.txt"}
                If Not names.SequenceEqual(wanted) Then
                    context.Say("expected {0}", String.Join(", ", wanted))
                    Return RecipeOutcome.Failed
                End If
                Dim target = context.PathTo("unpacked")
                If Not archive.ExtractAll(target).Succeeded Then Return RecipeOutcome.Failed
                If File.ReadAllText(Path.Combine(target, "docs", "readme.txt")) <> File.ReadAllText(Path.Combine(source, "readme.txt")) Then
                    context.Say("the renamed entry did not keep its content")
                    Return RecipeOutcome.Failed
                End If
            End Using
            context.Say("removed, renamed and added; the original is unchanged at {0}",
                        RecipeContext.Readable(New FileInfo(archivePath).Length))
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Remove, rename and add inside a <c>.7z</c> — the same <see cref="ArchiveUpdate"/> calls as for a ZIP.
    /// </summary>
    /// <remarks>
    /// The difference is underneath, and worth knowing. A ZIP update carries untouched entries across still
    /// compressed; a 7z one cannot, because a solid 7z compresses its entries together and taking one out
    /// changes the bytes of everything after it. So a 7z update decodes what it keeps and writes it again,
    /// with the settings you pass governing the whole result — and the settings' password is also what opens
    /// the source if it is encrypted. Like every update, it writes a new file and never touches the original.
    /// </remarks>
    internal static class SevenZipUpdateRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("books.7z");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                if (!writer.AddDirectory(source, null, null).Succeeded || !writer.Complete().Succeeded)
                {
                    context.Say("the starting archive could not be written");
                    return RecipeOutcome.Failed;
                }
            }

            var cover = context.PathTo("cover.txt");
            File.WriteAllText(cover, "a cover added by the update");
            var update = new ArchiveUpdate(archivePath);
            update.Remove("data.bin");
            update.Rename("readme.txt", "docs/readme.txt");
            update.AddOrReplaceFile(cover, "cover.txt");
            var updatedPath = context.PathTo("books-updated.7z");
            var result = update.Apply(updatedPath, null);
            if (!result.Succeeded)
            {
                context.Say(result.ToString());
                return RecipeOutcome.Failed;
            }

            var opened = Archive.Open(updatedPath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var names = new List<string>();
                foreach (var entry in archive.Entries)
                {
                    if (!entry.IsDirectory) names.Add(entry.Name);
                }

                names.Sort(StringComparer.Ordinal);
                context.Say("the updated archive holds {0}", string.Join(", ", names));
                var wanted = new[] { "cover.txt", "docs/readme.txt", "documents/notes.txt" };
                if (!names.SequenceEqual(wanted))
                {
                    context.Say("expected {0}", string.Join(", ", wanted));
                    return RecipeOutcome.Failed;
                }

                var target = context.PathTo("unpacked");
                if (!archive.ExtractAll(target).Succeeded) return RecipeOutcome.Failed;
                if (File.ReadAllText(Path.Combine(target, "docs", "readme.txt")) != File.ReadAllText(Path.Combine(source, "readme.txt")))
                {
                    context.Say("the renamed entry did not keep its content");
                    return RecipeOutcome.Failed;
                }
            }

            context.Say("removed, renamed and added; the original is unchanged at {0}",
                        RecipeContext.Readable(new FileInfo(archivePath).Length));
            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Diagnostics

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Span an archive across removable disks, asking for each one as it is needed, and read it back the same way.
    ''' </summary>
    ''' <remarks>
    ''' <see cref="OperationMonitor.VolumeNeeded"/> is the prompt a backup program shows: "insert disk 3". Here a
    ''' folder plays the drive and another the shelf of disks, and every disk carries the archive's own name, as
    ''' PKZIP's floppies did. Writing closes each disk before asking for the next; reading asks for each disk as
    ''' its bytes are wanted and refuses one that is not the disk it asked for. On a real drive the handler would
    ''' show a message box and leave <see cref="VolumeNeededEventArgs.Path"/> alone. To fill each disk rather than
    ''' cut it at a fixed size, pass <see cref="ArchiveWriter.FillEachMedium"/> as the volume size.
    ''' </remarks>
    Friend Module SpannedDisksRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.PathTo("documents")
            Directory.CreateDirectory(source)
            For index = 1 To 5
                File.WriteAllBytes(Path.Combine(source, $"scan{index}.bin"), RecipeContext.PseudoRandom(60000, index))
            Next
            Dim drive = context.PathTo("drive")
            Dim shelf = context.PathTo("shelf")
            Directory.CreateDirectory(drive)
            Dim archivePath = Path.Combine(drive, "backup.zip")

            ' Writing: when a disk is full, it goes on the shelf and a blank one goes in.
            Dim writing As New OperationMonitor()
            AddHandler writing.VolumeNeeded,
                Sub(sender, e)
                    Dim full = Path.Combine(shelf, $"disk{e.VolumeNumber - 1}")
                    Directory.CreateDirectory(full)
                    File.Move(Directory.GetFiles(drive)(0), Path.Combine(full, "backup.zip"))
                End Sub
            Dim started = ArchiveWriter.CreateSpanned(archivePath, 65536, Nothing, writing)
            If Not started.Succeeded Then Return RecipeOutcome.Failed
            Using writer = started.Writer
                If Not writer.AddDirectory(source, Nothing, Nothing).Succeeded OrElse Not writer.Complete().Succeeded Then Return RecipeOutcome.Failed
            End Using
            Dim disks = Directory.GetDirectories(shelf).Length + 1
            Directory.CreateDirectory(Path.Combine(shelf, $"disk{disks}"))
            File.Copy(archivePath, Path.Combine(shelf, $"disk{disks}", "backup.zip"))
            context.Say("{0} files spanned across {1} disks of 64 KiB", 5, disks)

            ' Reading: the last disk is in the drive; every other one is asked for when it is wanted.
            Dim changes = 0
            Dim reading As New OperationMonitor()
            AddHandler reading.VolumeNeeded,
                Sub(sender, e)
                    Dim wanted = If(e.VolumeNumber = 0, disks, e.VolumeNumber)
                    File.Copy(Path.Combine(shelf, $"disk{wanted}", "backup.zip"), archivePath, overwrite:=True)
                    e.Path = archivePath
                    changes += 1
                End Sub
            Dim opened = Archive.Open(archivePath, New ArchiveOpenOptions() With {.Monitor = reading})
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Dim restored = context.PathTo("restored")
            Using archive = opened.Archive
                Dim result = archive.ExtractAll(restored)
                If Not result.Succeeded Then
                    context.Say(result.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using
            For index = 1 To 5
                Dim name = $"scan{index}.bin"
                If Not File.ReadAllBytes(Path.Combine(source, name)).AsSpan().SequenceEqual(File.ReadAllBytes(Path.Combine(restored, name))) Then Return RecipeOutcome.Failed
            Next
            context.Say("read back byte for byte after {0} disk changes", changes)
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;
using Bastion.Archive.Diagnostics;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Span an archive across removable disks, asking for each one as it is needed, and read it back the same way.
    /// </summary>
    /// <remarks>
    /// <see cref="OperationMonitor.VolumeNeeded"/> is the prompt a backup program shows: "insert disk 3". Here a
    /// folder plays the drive and another the shelf of disks, and every disk carries the archive's own name, as
    /// PKZIP's floppies did. Writing closes each disk before asking for the next; reading asks for each disk as
    /// its bytes are wanted and refuses one that is not the disk it asked for. On a real drive the handler would
    /// show a message box and leave <see cref="VolumeNeededEventArgs.Path"/> alone. To fill each disk rather than
    /// cut it at a fixed size, pass <see cref="ArchiveWriter.FillEachMedium"/> as the volume size.
    /// </remarks>
    internal static class SpannedDisksRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.PathTo("documents");
            Directory.CreateDirectory(source);
            for (var index = 1; index <= 5; index++)
            {
                File.WriteAllBytes(Path.Combine(source, $"scan{index}.bin"), RecipeContext.PseudoRandom(60000, index));
            }

            var drive = context.PathTo("drive");
            var shelf = context.PathTo("shelf");
            Directory.CreateDirectory(drive);
            var archivePath = Path.Combine(drive, "backup.zip");

            // Writing: when a disk is full, it goes on the shelf and a blank one goes in.
            var writing = new OperationMonitor();
            writing.VolumeNeeded += (sender, e) =>
            {
                var full = Path.Combine(shelf, $"disk{e.VolumeNumber - 1}");
                Directory.CreateDirectory(full);
                File.Move(Directory.GetFiles(drive)[0], Path.Combine(full, "backup.zip"));
            };
            var started = ArchiveWriter.CreateSpanned(archivePath, 65536, null, writing);
            if (!started.Succeeded) return RecipeOutcome.Failed;
            using (var writer = started.Writer)
            {
                if (!writer.AddDirectory(source, null, null).Succeeded || !writer.Complete().Succeeded) return RecipeOutcome.Failed;
            }

            var disks = Directory.GetDirectories(shelf).Length + 1;
            Directory.CreateDirectory(Path.Combine(shelf, $"disk{disks}"));
            File.Copy(archivePath, Path.Combine(shelf, $"disk{disks}", "backup.zip"));
            context.Say("{0} files spanned across {1} disks of 64 KiB", 5, disks);

            // Reading: the last disk is in the drive; every other one is asked for when it is wanted.
            var changes = 0;
            var reading = new OperationMonitor();
            reading.VolumeNeeded += (sender, e) =>
            {
                var wanted = e.VolumeNumber == 0 ? disks : e.VolumeNumber;
                File.Copy(Path.Combine(shelf, $"disk{wanted}", "backup.zip"), archivePath, overwrite: true);
                e.Path = archivePath;
                changes++;
            };
            var opened = Archive.Open(archivePath, new ArchiveOpenOptions { Monitor = reading });
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            var restored = context.PathTo("restored");
            using (var archive = opened.Archive)
            {
                var result = archive.ExtractAll(restored);
                if (!result.Succeeded)
                {
                    context.Say(result.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            for (var index = 1; index <= 5; index++)
            {
                var name = $"scan{index}.bin";
                if (!File.ReadAllBytes(Path.Combine(source, name)).AsSpan().SequenceEqual(File.ReadAllBytes(Path.Combine(restored, name)))) return RecipeOutcome.Failed;
            }

            context.Say("read back byte for byte after {0} disk changes", changes);
            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Write a split archive and read it back from its first volume.
    ''' </summary>
    ''' <remarks>
    ''' There are two kinds of split ZIP and they are not the same thing. The modern kind, which 7-Zip
    ''' writes and which this library writes, is one ordinary archive cut into <c>name.zip.001</c>,
    ''' <c>name.zip.002</c> and so on; any reader that can concatenate them can read it. The older PKWARE kind
    ''' uses <c>name.z01</c>, <c>name.z02</c>, <c>name.zip</c>, records a disk number in every central header
    ''' and lets an entry's data cross a volume boundary. This library reads both, and the two are told apart by
    ''' the end record's own disk number.
    ''' Opening takes any volume of the set: the reader finds the others by name and keeps exactly one of them
    ''' open at a time, so a hundred-volume set costs one file handle.
    ''' </remarks>
    Friend Module SplitVolumesRecipe

        ''' <summary>The smallest volume the writer accepts, which makes a small sample produce several.</summary>
        Private Const VolumeSize As Long = 65536

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            ' Enough incompressible data to need several volumes at 64 KiB each.
            File.WriteAllBytes(Path.Combine(source, "payload.bin"), RecipeContext.PseudoRandom(300000, 7))

            Dim archivePath = context.PathTo("split.zip")
            Dim started = ArchiveWriter.CreateSplit(archivePath, VolumeSize, Nothing, Nothing)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, Nothing, Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim volumes = Directory.GetFiles(context.WorkingDirectory, "split.zip.*")
            Array.Sort(volumes, StringComparer.Ordinal)
            context.Say("{0} volumes at {1} each:", volumes.Length, RecipeContext.Readable(VolumeSize))
            For Each volume In volumes
                context.Say("  {0}  {1}", Path.GetFileName(volume), RecipeContext.Readable(New FileInfo(volume).Length))
            Next
            If volumes.Length < 2 Then
                context.Say("the sample did not need splitting, so this recipe proved nothing")
                Return RecipeOutcome.Failed
            End If
            ' No volume is bigger than asked for. That is the whole promise of a volume size.
            For Each volume In volumes
                If New FileInfo(volume).Length > VolumeSize Then
                    context.Say("a volume exceeded the size asked for: " & Path.GetFileName(volume))
                    Return RecipeOutcome.Failed
                End If
            Next

            ' Opening from the first volume; the reader finds the rest by name.
            Dim opened = Archive.Open(volumes(0))
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                context.Say("opened from {0}: {1} entries across {2} volumes",
                            Path.GetFileName(volumes(0)), archive.Entries.Count, archive.VolumeCount)
                If archive.VolumeCount <> volumes.Length Then
                    context.Say("the reader did not find every volume")
                    Return RecipeOutcome.Failed
                End If
                Dim target = context.PathTo("out")
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim expected = File.ReadAllBytes(Path.Combine(source, "payload.bin"))
                Dim recovered = File.ReadAllBytes(Path.Combine(target, "payload.bin"))
                If Not RecipeContext.SameBytes(expected, recovered) Then
                    context.Say("the payload did not survive the volume boundaries")
                    Return RecipeOutcome.Failed
                End If
                context.Say("payload.bin came back byte for byte across {0} volumes", archive.VolumeCount)
            End Using

            ' A missing volume is reported as a missing volume, not as a corrupt archive.
            Dim removed = volumes(volumes.Length - 1)
            Dim kept = removed & ".kept"
            File.Move(removed, kept)
            Dim incomplete = Archive.Open(volumes(0))
            If incomplete.Succeeded Then
                Using archive = incomplete.Archive
                    Dim tested = archive.Test(Nothing)
                    context.Say("with the last volume missing, the test returned {0}", tested.ErrorCode)
                    If tested.Succeeded Then
                        context.Say("an incomplete set should not pass")
                        Return RecipeOutcome.Failed
                    End If
                End Using
            Else
                context.Say("with the last volume missing, opening returned {0}", incomplete.ErrorCode)
            End If
            File.Move(kept, removed)
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Write a split archive and read it back from its first volume.
    /// </summary>
    /// <remarks>
    /// There are two kinds of split ZIP and they are not the same thing. The modern kind, which 7-Zip
    /// writes and which this library writes, is one ordinary archive cut into <c>name.zip.001</c>,
    /// <c>name.zip.002</c> and so on; any reader that can concatenate them can read it. The older PKWARE kind
    /// uses <c>name.z01</c>, <c>name.z02</c>, <c>name.zip</c>, records a disk number in every central header
    /// and lets an entry's data cross a volume boundary. This library reads both, and the two are told apart by
    /// the end record's own disk number.
    /// Opening takes any volume of the set: the reader finds the others by name and keeps exactly one of them
    /// open at a time, so a hundred-volume set costs one file handle.
    /// </remarks>
    internal static class SplitVolumesRecipe
    {
        /// <summary>The smallest volume the writer accepts, which makes a small sample produce several.</summary>
        private const long VolumeSize = 65536;

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            // Enough incompressible data to need several volumes at 64 KiB each.
            File.WriteAllBytes(Path.Combine(source, "payload.bin"), RecipeContext.PseudoRandom(300000, 7));

            var archivePath = context.PathTo("split.zip");
            var started = ArchiveWriter.CreateSplit(archivePath, VolumeSize, null, null);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, null, null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return RecipeOutcome.Failed;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            var volumes = Directory.GetFiles(context.WorkingDirectory, "split.zip.*");
            Array.Sort(volumes, StringComparer.Ordinal);
            context.Say("{0} volumes at {1} each:", volumes.Length, RecipeContext.Readable(VolumeSize));
            foreach (var volume in volumes)
            {
                context.Say("  {0}  {1}", Path.GetFileName(volume), RecipeContext.Readable(new FileInfo(volume).Length));
            }

            if (volumes.Length < 2)
            {
                context.Say("the sample did not need splitting, so this recipe proved nothing");
                return RecipeOutcome.Failed;
            }

            // No volume is bigger than asked for. That is the whole promise of a volume size.
            foreach (var volume in volumes)
            {
                if (new FileInfo(volume).Length > VolumeSize)
                {
                    context.Say("a volume exceeded the size asked for: " + Path.GetFileName(volume));
                    return RecipeOutcome.Failed;
                }
            }

            // Opening from the first volume; the reader finds the rest by name.
            var opened = Archive.Open(volumes[0]);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                context.Say("opened from {0}: {1} entries across {2} volumes",
                    Path.GetFileName(volumes[0]), archive.Entries.Count, archive.VolumeCount);
                if (archive.VolumeCount != volumes.Length)
                {
                    context.Say("the reader did not find every volume");
                    return RecipeOutcome.Failed;
                }

                var target = context.PathTo("out");
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                var expected = File.ReadAllBytes(Path.Combine(source, "payload.bin"));
                var recovered = File.ReadAllBytes(Path.Combine(target, "payload.bin"));
                if (!RecipeContext.SameBytes(expected, recovered))
                {
                    context.Say("the payload did not survive the volume boundaries");
                    return RecipeOutcome.Failed;
                }

                context.Say("payload.bin came back byte for byte across {0} volumes", archive.VolumeCount);
            }

            // A missing volume is reported as a missing volume, not as a corrupt archive.
            var removed = volumes[volumes.Length - 1];
            var kept = removed + ".kept";
            File.Move(removed, kept);
            var incomplete = Archive.Open(volumes[0]);
            if (incomplete.Succeeded)
            {
                using (var archive = incomplete.Archive)
                {
                    var tested = archive.Test(null);
                    context.Say("with the last volume missing, the test returned {0}", tested.ErrorCode);
                    if (tested.Succeeded)
                    {
                        context.Say("an incomplete set should not pass");
                        return RecipeOutcome.Failed;
                    }
                }
            }
            else
            {
                context.Say("with the last volume missing, opening returned {0}", incomplete.ErrorCode);
            }

            File.Move(kept, removed);
            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Collections.Generic
Imports System.IO
Imports System.Text
Imports Bastion.Archive
Imports Bastion.Archive.Diagnostics

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Write and read an archive that never touches the disk.
    ''' </summary>
    ''' <remarks>
    ''' Both ends of the library take a stream, so an archive can be built into memory, into a response body or
    ''' into a network socket, and read back from one. Two rules apply to a caller-supplied stream: the library
    ''' never disposes it, because it did not open it, and writing needs a stream it can seek back over to
    ''' rewrite each local header once the entry's true size is known.
    ''' This is also the recipe that shows the events. The monitor raises <c>EntryStarted</c>,
    ''' <c>EntryCompleted</c>, <c>Progress</c> and <c>LogMessage</c>, and marshals each one through the
    ''' synchronisation context it captured when it was built — which is why a user interface can update a
    ''' progress bar straight from a handler without an <c>Invoke</c> of its own.
    ''' </remarks>
    Friend Module StreamingWriterRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim documents As New Dictionary(Of String, Byte())(StringComparer.Ordinal) From {
                {"reports/january.txt", Encoding.UTF8.GetBytes(New String("J"c, 30000))},
                {"reports/february.txt", Encoding.UTF8.GetBytes(New String("F"c, 25000))},
                {"images/noise.bin", RecipeContext.PseudoRandom(12000, 3)}
            }

            Dim started As List(Of String) = New List(Of String)()
            Dim completed As New List(Of String)()
            Dim progressReports = 0
            Dim monitor As New OperationMonitor()
            AddHandler monitor.EntryStarted, Sub(sender, e) started.Add(e.EntryPath)
            AddHandler monitor.EntryCompleted, Sub(sender, e) completed.Add(e.EntryPath)
            AddHandler monitor.Progress, Sub(sender, e) progressReports += 1
            ' Progress is throttled so a handler cannot be swamped; for a sample that finishes in milliseconds,
            ' asking for every report is what makes the events visible at all.
            monitor.ProgressInterval = TimeSpan.Zero

            Dim archiveBytes As Byte()
            Using buffer As New MemoryStream()
                Dim starting = ArchiveWriter.Create(buffer, Nothing, monitor)
                If Not starting.Succeeded Then
                    context.Say(starting.ToString())
                    Return RecipeOutcome.Failed
                End If
                Using writer = starting.Writer
                    For Each document In documents
                        Using source As New MemoryStream(document.Value, False)
                            Dim added = writer.AddStream(source, document.Key, Nothing)
                            If Not added.Succeeded Then
                                context.Say(added.ToString())
                                Return RecipeOutcome.Failed
                            End If
                        End Using
                    Next
                    Dim finished = writer.Complete()
                    If Not finished.Succeeded Then
                        context.Say(finished.ToString())
                        Return RecipeOutcome.Failed
                    End If
                End Using
                ' The stream is still open and still ours: the writer never disposes what it was handed.
                If Not buffer.CanRead Then
                    context.Say("the writer disposed a stream it did not own")
                    Return RecipeOutcome.Failed
                End If
                archiveBytes = buffer.ToArray()
            End Using

            context.Say("built a {0} archive entirely in memory", RecipeContext.Readable(archiveBytes.Length))
            context.Say("events: {0} entries started, {1} completed, {2} progress reports",
                        started.Count, completed.Count, progressReports)
            If started.Count <> documents.Count OrElse completed.Count <> documents.Count Then
                context.Say("every entry should have raised both events")
                Return RecipeOutcome.Failed
            End If
            If progressReports = 0 Then
                context.Say("no progress was reported at all")
                Return RecipeOutcome.Failed
            End If

            ' Read it back from a stream too, without ever writing a file.
            Using buffer As New MemoryStream(archiveBytes, False)
                Dim options As New ArchiveOpenOptions() With {.LeaveStreamOpen = True}
                Dim opened = Archive.Open(buffer, options)
                If Not opened.Succeeded Then
                    context.Say(opened.ToString())
                    Return RecipeOutcome.Failed
                End If
                Using archive = opened.Archive
                    For Each entry In archive.Entries
                        Using recovered As New MemoryStream()
                            Dim streamed = archive.ExtractToStream(entry, recovered, Nothing)
                            If Not streamed.Succeeded Then
                                context.Say(streamed.ToString())
                                Return RecipeOutcome.Failed
                            End If
                            If Not RecipeContext.SameBytes(documents(entry.Name), recovered.ToArray()) Then
                                context.Say("'" & entry.Name & "' did not survive the round trip")
                                Return RecipeOutcome.Failed
                            End If
                        End Using
                    Next
                    context.Say("all {0} entries read back from memory and matched", archive.Entries.Count)
                End Using
                If Not buffer.CanRead Then
                    context.Say("LeaveStreamOpen was asked for and not honoured")
                    Return RecipeOutcome.Failed
                End If
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using Bastion.Archive.Diagnostics;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Write and read an archive that never touches the disk.
    /// </summary>
    /// <remarks>
    /// Both ends of the library take a stream, so an archive can be built into memory, into a response body or
    /// into a network socket, and read back from one. Two rules apply to a caller-supplied stream: the library
    /// never disposes it, because it did not open it, and writing needs a stream it can seek back over to
    /// rewrite each local header once the entry's true size is known.
    /// This is also the recipe that shows the events. The monitor raises <c>EntryStarted</c>,
    /// <c>EntryCompleted</c>, <c>Progress</c> and <c>LogMessage</c>, and marshals each one through the
    /// synchronisation context it captured when it was built — which is why a user interface can update a
    /// progress bar straight from a handler without an <c>Invoke</c> of its own.
    /// </remarks>
    internal static class StreamingWriterRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var documents = new Dictionary<string, byte[]>(StringComparer.Ordinal)
            {
                { "reports/january.txt", Encoding.UTF8.GetBytes(new string('J', 30000)) },
                { "reports/february.txt", Encoding.UTF8.GetBytes(new string('F', 25000)) },
                { "images/noise.bin", RecipeContext.PseudoRandom(12000, 3) }
            };

            var entriesStarted = new List<string>();
            var entriesCompleted = new List<string>();
            var progressReports = 0;
            var monitor = new OperationMonitor();
            monitor.EntryStarted += (sender, e) => entriesStarted.Add(e.EntryPath);
            monitor.EntryCompleted += (sender, e) => entriesCompleted.Add(e.EntryPath);
            monitor.Progress += (sender, e) => progressReports++;
            // Progress is throttled so a handler cannot be swamped; for a sample that finishes in milliseconds,
            // asking for every report is what makes the events visible at all.
            monitor.ProgressInterval = TimeSpan.Zero;

            byte[] archiveBytes;
            using (var buffer = new MemoryStream())
            {
                var starting = ArchiveWriter.Create(buffer, null, monitor);
                if (!starting.Succeeded)
                {
                    context.Say(starting.ToString());
                    return RecipeOutcome.Failed;
                }

                using (var writer = starting.Writer)
                {
                    foreach (var document in documents)
                    {
                        using (var source = new MemoryStream(document.Value, false))
                        {
                            var added = writer.AddStream(source, document.Key, null);
                            if (!added.Succeeded)
                            {
                                context.Say(added.ToString());
                                return RecipeOutcome.Failed;
                            }
                        }
                    }

                    var finished = writer.Complete();
                    if (!finished.Succeeded)
                    {
                        context.Say(finished.ToString());
                        return RecipeOutcome.Failed;
                    }
                }

                // The stream is still open and still ours: the writer never disposes what it was handed.
                if (!buffer.CanRead)
                {
                    context.Say("the writer disposed a stream it did not own");
                    return RecipeOutcome.Failed;
                }

                archiveBytes = buffer.ToArray();
            }

            context.Say("built a {0} archive entirely in memory", RecipeContext.Readable(archiveBytes.Length));
            context.Say("events: {0} entries started, {1} completed, {2} progress reports",
                entriesStarted.Count, entriesCompleted.Count, progressReports);
            if (entriesStarted.Count != documents.Count || entriesCompleted.Count != documents.Count)
            {
                context.Say("every entry should have raised both events");
                return RecipeOutcome.Failed;
            }

            if (progressReports == 0)
            {
                context.Say("no progress was reported at all");
                return RecipeOutcome.Failed;
            }

            // Read it back from a stream too, without ever writing a file.
            using (var buffer = new MemoryStream(archiveBytes, false))
            {
                var options = new ArchiveOpenOptions { LeaveStreamOpen = true };
                var opened = Archive.Open(buffer, options);
                if (!opened.Succeeded)
                {
                    context.Say(opened.ToString());
                    return RecipeOutcome.Failed;
                }

                using (var archive = opened.Archive)
                {
                    foreach (var entry in archive.Entries)
                    {
                        using (var recovered = new MemoryStream())
                        {
                            var streamed = archive.ExtractToStream(entry, recovered, null);
                            if (!streamed.Succeeded)
                            {
                                context.Say(streamed.ToString());
                                return RecipeOutcome.Failed;
                            }

                            if (!RecipeContext.SameBytes(documents[entry.Name], recovered.ToArray()))
                            {
                                context.Say("'" + entry.Name + "' did not survive the round trip");
                                return RecipeOutcome.Failed;
                            }
                        }
                    }

                    context.Say("all {0} entries read back from memory and matched", archive.Entries.Count);
                }

                if (!buffer.CanRead)
                {
                    context.Say("LeaveStreamOpen was asked for and not honoured");
                    return RecipeOutcome.Failed;
                }
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Formats.Tar

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Make and read a <c>.tar.gz</c> in one call each.
    ''' </summary>
    ''' <remarks>
    ''' A compressed tarball is two formats stacked: tar decides what the entries are, gzip decides how the
    ''' bytes travel, and neither knows about the other. <c>TarArchive</c> takes the compressor from the
    ''' archive's name, so <c>.tar.gz</c> and <c>.tgz</c> mean the same thing and neither needs a setting.
    ''' <para>
    ''' Like every archive-level call in this library it returns an <see cref="OperationResult"/> and never
    ''' throws at the caller, and it canonicalises entry paths on the way out, so an archive
    ''' carrying <c>../../etc/passwd</c> is refused rather than obeyed.
    ''' </para>
    ''' </remarks>
    Friend Module TarGzRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("bundle.tar.gz")

            Dim created = TarArchive.CreateFromDirectory(source, archivePath)
            If Not created.Succeeded Then
                context.Say(created.ToString())
                Return RecipeOutcome.Failed
            End If

            Dim plain = New FileInfo(archivePath).Length
            context.Say("wrote {0} from {1} of files", RecipeContext.Readable(plain), RecipeContext.Readable(SizeOf(source)))

            ' The short spelling means exactly the same thing, which is worth showing because half the world
            ' writes one and half the other.
            Dim shortName = context.PathTo("bundle.tgz")
            Dim alsoCreated = TarArchive.CreateFromDirectory(source, shortName)
            If Not alsoCreated.Succeeded Then
                context.Say(alsoCreated.ToString())
                Return RecipeOutcome.Failed
            End If
            context.Say(".tgz is the same archive: {0}", RecipeContext.Readable(New FileInfo(shortName).Length))

            Dim target = context.PathTo("unpacked")
            Dim extracted = TarArchive.ExtractToDirectory(archivePath, target)
            If Not extracted.Succeeded Then
                context.Say(extracted.ToString())
                Return RecipeOutcome.Failed
            End If

            ' The proof is the bytes, not the absence of an error.
            If Not SameTree(source, target, context) Then Return RecipeOutcome.Failed
            context.Say("every file came back with the same bytes")
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>How much is in a directory, so the archive's size means something.</summary>
        Friend Function SizeOf(root As String) As Long
            Dim total = 0L
            For Each item In Directory.GetFiles(root, "*", SearchOption.AllDirectories)
                total += New FileInfo(item).Length
            Next
            Return total
        End Function

        ''' <summary>
        ''' Every file under one root is under the other with the same bytes, which is what a round trip means.
        ''' </summary>
        Friend Function SameTree(source As String, target As String, context As RecipeContext) As Boolean
            For Each item In Directory.GetFiles(source, "*", SearchOption.AllDirectories)
                Dim relative = item.Substring(source.Length).TrimStart(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar)
                Dim copied = Path.Combine(target, relative)
                If Not File.Exists(copied) Then
                    context.Say("'{0}' did not come back", relative)
                    Return False
                End If
                If Not RecipeContext.SameBytes(File.ReadAllBytes(item), File.ReadAllBytes(copied)) Then
                    context.Say("'{0}' came back with different bytes", relative)
                    Return False
                End If
            Next
            Return True
        End Function

    End Module

End Namespace

C#

using System.IO;
using Bastion.Archive.Formats.Tar;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Make and read a <c>.tar.gz</c> in one call each.
    /// </summary>
    /// <remarks>
    /// A compressed tarball is two formats stacked: tar decides what the entries are, gzip decides how the
    /// bytes travel, and neither knows about the other. <c>TarArchive</c> takes the compressor from the
    /// archive's name, so <c>.tar.gz</c> and <c>.tgz</c> mean the same thing and neither needs a setting.
    /// <para>
    /// Like every archive-level call in this library it returns an <see cref="OperationResult"/> and never
    /// throws at the caller, and it canonicalises entry paths on the way out, so an archive
    /// carrying <c>../../etc/passwd</c> is refused rather than obeyed.
    /// </para>
    /// </remarks>
    internal static class TarGzRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("bundle.tar.gz");

            var created = TarArchive.CreateFromDirectory(source, archivePath);
            if (!created.Succeeded)
            {
                context.Say(created.ToString());
                return RecipeOutcome.Failed;
            }

            var plain = new FileInfo(archivePath).Length;
            context.Say("wrote {0} from {1} of files", RecipeContext.Readable(plain), RecipeContext.Readable(SizeOf(source)));

            // The short spelling means exactly the same thing, which is worth showing because half the world
            // writes one and half the other.
            var shortName = context.PathTo("bundle.tgz");
            var alsoCreated = TarArchive.CreateFromDirectory(source, shortName);
            if (!alsoCreated.Succeeded)
            {
                context.Say(alsoCreated.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say(".tgz is the same archive: {0}", RecipeContext.Readable(new FileInfo(shortName).Length));

            var target = context.PathTo("unpacked");
            var extracted = TarArchive.ExtractToDirectory(archivePath, target);
            if (!extracted.Succeeded)
            {
                context.Say(extracted.ToString());
                return RecipeOutcome.Failed;
            }

            // The proof is the bytes, not the absence of an error.
            if (!SameTree(source, target, context)) return RecipeOutcome.Failed;
            context.Say("every file came back with the same bytes");
            return RecipeOutcome.Passed;
        }

        /// <summary>How much is in a directory, so the archive's size means something.</summary>
        internal static long SizeOf(string root)
        {
            var total = 0L;
            foreach (var item in Directory.GetFiles(root, "*", SearchOption.AllDirectories))
            {
                total += new FileInfo(item).Length;
            }

            return total;
        }

        /// <summary>
        /// Every file under one root is under the other with the same bytes, which is what a round trip means.
        /// </summary>
        internal static bool SameTree(string source, string target, RecipeContext context)
        {
            foreach (var item in Directory.GetFiles(source, "*", SearchOption.AllDirectories))
            {
                var relative = item.Substring(source.Length).TrimStart(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
                var copied = Path.Combine(target, relative);
                if (!File.Exists(copied))
                {
                    context.Say("'{0}' did not come back", relative);
                    return false;
                }

                if (!RecipeContext.SameBytes(File.ReadAllBytes(item), File.ReadAllBytes(copied)))
                {
                    context.Say("'{0}' came back with different bytes", relative);
                    return false;
                }
            }

            return true;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Formats.Tar

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Make a <c>.tar.xz</c>, choose the tar dialect, and make the same bytes twice.
    ''' </summary>
    ''' <remarks>
    ''' Everything <c>TarGz</c> shows applies here with a different compressor, so what this recipe is
    ''' actually about is <see cref="TarArchiveOptions"/>: which tar dialect the entries are written in, how
    ''' hard the compressor works, and — the one worth having — a fixed modification time.
    ''' <para>
    ''' A fixed time is what makes an archive reproducible. Two runs over the same files
    ''' normally differ, because the entries carry the files' timestamps and those change when the files are
    ''' rewritten; pinning the time makes the archive a function of its contents alone, which is what lets a
    ''' build system compare a hash and a release be verified by whoever receives it.
    ''' </para>
    ''' </remarks>
    Friend Module TarXzRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()

            Dim options As New TarArchiveOptions()
            options.Format = TarFormat.Pax
            options.CompressionLevel = 6
            ' Midnight on the first of January 2020, in Unix seconds. Any fixed value would do; what matters is
            ' that it does not come from the file system.
            options.FixedModifiedUnixTime = 1577836800L

            Dim firstPath = context.PathTo("first.tar.xz")
            Dim created = TarArchive.CreateFromDirectory(source, firstPath, options)
            If Not created.Succeeded Then
                context.Say(created.ToString())
                Return RecipeOutcome.Failed
            End If
            context.Say("pax entries, xz level 6: {0}", RecipeContext.Readable(New FileInfo(firstPath).Length))

            ' The same inputs and the same settings, written again after the files have been touched.
            For Each item In Directory.GetFiles(source, "*", SearchOption.AllDirectories)
                File.SetLastWriteTimeUtc(item, DateTime.UtcNow)
            Next
            Dim secondPath = context.PathTo("second.tar.xz")
            Dim again = TarArchive.CreateFromDirectory(source, secondPath, options)
            If Not again.Succeeded Then
                context.Say(again.ToString())
                Return RecipeOutcome.Failed
            End If

            If Not RecipeContext.SameBytes(File.ReadAllBytes(firstPath), File.ReadAllBytes(secondPath)) Then
                context.Say("the two archives differ, so the timestamps were not actually pinned")
                Return RecipeOutcome.Failed
            End If
            context.Say("byte-identical after the files were touched, because the time came from the settings")

            ' GNU rather than pax is a different archive of the same files, which is the point of the setting.
            Dim gnuOptions As New TarArchiveOptions()
            gnuOptions.Format = TarFormat.Gnu
            gnuOptions.CompressionLevel = 6
            gnuOptions.FixedModifiedUnixTime = 1577836800L
            Dim gnuPath = context.PathTo("gnu.tar.xz")
            Dim gnu = TarArchive.CreateFromDirectory(source, gnuPath, gnuOptions)
            If Not gnu.Succeeded Then
                context.Say(gnu.ToString())
                Return RecipeOutcome.Failed
            End If
            context.Say("the same files as GNU tar: {0}", RecipeContext.Readable(New FileInfo(gnuPath).Length))

            Dim target = context.PathTo("unpacked")
            Dim extracted = TarArchive.ExtractToDirectory(firstPath, target)
            If Not extracted.Succeeded Then
                context.Say(extracted.ToString())
                Return RecipeOutcome.Failed
            End If
            If Not TarGzRecipe.SameTree(source, target, context) Then Return RecipeOutcome.Failed
            context.Say("every file came back with the same bytes")
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;
using Bastion.Archive.Formats.Tar;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Make a <c>.tar.xz</c>, choose the tar dialect, and make the same bytes twice.
    /// </summary>
    /// <remarks>
    /// Everything <c>TarGz</c> shows applies here with a different compressor, so what this recipe is
    /// actually about is <see cref="TarArchiveOptions"/>: which tar dialect the entries are written in, how
    /// hard the compressor works, and — the one worth having — a fixed modification time.
    /// <para>
    /// A fixed time is what makes an archive reproducible. Two runs over the same files
    /// normally differ, because the entries carry the files' timestamps and those change when the files are
    /// rewritten; pinning the time makes the archive a function of its contents alone, which is what lets a
    /// build system compare a hash and a release be verified by whoever receives it.
    /// </para>
    /// </remarks>
    internal static class TarXzRecipe
    {
        /// <summary>Midnight on the first of January 2020, in Unix seconds.</summary>
        private const long FixedTime = 1577836800L;

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();

            var options = new TarArchiveOptions
            {
                Format = TarFormat.Pax,
                CompressionLevel = 6,
                // Any fixed value would do; what matters is that it does not come from the file system.
                FixedModifiedUnixTime = FixedTime
            };

            var firstPath = context.PathTo("first.tar.xz");
            var created = TarArchive.CreateFromDirectory(source, firstPath, options);
            if (!created.Succeeded)
            {
                context.Say(created.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say("pax entries, xz level 6: {0}", RecipeContext.Readable(new FileInfo(firstPath).Length));

            // The same inputs and the same settings, written again after the files have been touched.
            foreach (var item in Directory.GetFiles(source, "*", SearchOption.AllDirectories))
            {
                File.SetLastWriteTimeUtc(item, DateTime.UtcNow);
            }

            var secondPath = context.PathTo("second.tar.xz");
            var again = TarArchive.CreateFromDirectory(source, secondPath, options);
            if (!again.Succeeded)
            {
                context.Say(again.ToString());
                return RecipeOutcome.Failed;
            }

            if (!RecipeContext.SameBytes(File.ReadAllBytes(firstPath), File.ReadAllBytes(secondPath)))
            {
                context.Say("the two archives differ, so the timestamps were not actually pinned");
                return RecipeOutcome.Failed;
            }

            context.Say("byte-identical after the files were touched, because the time came from the settings");

            // GNU rather than pax is a different archive of the same files, which is the point of the setting.
            var gnuOptions = new TarArchiveOptions
            {
                Format = TarFormat.Gnu,
                CompressionLevel = 6,
                FixedModifiedUnixTime = FixedTime
            };
            var gnuPath = context.PathTo("gnu.tar.xz");
            var gnu = TarArchive.CreateFromDirectory(source, gnuPath, gnuOptions);
            if (!gnu.Succeeded)
            {
                context.Say(gnu.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say("the same files as GNU tar: {0}", RecipeContext.Readable(new FileInfo(gnuPath).Length));

            var target = context.PathTo("unpacked");
            var extracted = TarArchive.ExtractToDirectory(firstPath, target);
            if (!extracted.Succeeded)
            {
                context.Say(extracted.ToString());
                return RecipeOutcome.Failed;
            }

            if (!TarGzRecipe.SameTree(source, target, context)) return RecipeOutcome.Failed;
            context.Say("every file came back with the same bytes");
            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Formats.Tar

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Make and read a <c>.tar.zst</c>, the newest of the compressed tarballs.
    ''' </summary>
    ''' <remarks>
    ''' This recipe used to demonstrate a refusal. Bastion.Archive decoded Zstandard without encoding it, so
    ''' asking for a <c>.tar.zst</c> was refused **by name** rather than quietly given a different compressor.
    ''' The Zstandard encoder was added later and the refusal went with it, so the recipe now does what the other three
    ''' tarball recipes do — which is the point: a caller writes the name they want and the library works out
    ''' the rest.
    ''' <para>
    ''' Zstandard is the one worth reaching for when the archive will be read more often than it is written.
    ''' It decompresses several times faster than gzip at a better ratio, which is why it has become the
    ''' default for container images and package managers.
    ''' </para>
    ''' </remarks>
    Friend Module TarZstRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()

            Dim archivePath = context.PathTo("bundle.tar.zst")
            Dim created = TarArchive.CreateFromDirectory(source, archivePath)
            If Not created.Succeeded Then
                context.Say(created.ToString())
                Return RecipeOutcome.Failed
            End If
            context.Say("wrote {0} from {1} of files",
                        RecipeContext.Readable(New FileInfo(archivePath).Length),
                        RecipeContext.Readable(TarGzRecipe.SizeOf(source)))

            ' The short spelling means the same thing here as it does for the others.
            Dim shortName = context.PathTo("bundle.tzst")
            Dim alsoCreated = TarArchive.CreateFromDirectory(source, shortName)
            If Not alsoCreated.Succeeded Then
                context.Say(alsoCreated.ToString())
                Return RecipeOutcome.Failed
            End If
            context.Say(".tzst is the same archive: {0}", RecipeContext.Readable(New FileInfo(shortName).Length))

            Dim target = context.PathTo("unpacked")
            Dim extracted = TarArchive.ExtractToDirectory(archivePath, target)
            If Not extracted.Succeeded Then
                context.Say(extracted.ToString())
                Return RecipeOutcome.Failed
            End If
            If Not TarGzRecipe.SameTree(source, target, context) Then Return RecipeOutcome.Failed
            context.Say("every file came back through the Zstandard decoder with the same bytes")

            ' Against the other three, on the same files, so the choice can be made on numbers.
            For Each name In New String() {"bundle.tar.gz", "bundle.tar.bz2", "bundle.tar.xz"}
                Dim other = context.PathTo(name)
                Dim made = TarArchive.CreateFromDirectory(source, other)
                If Not made.Succeeded Then
                    context.Say(made.ToString())
                    Return RecipeOutcome.Failed
                End If
                context.Say("  {0,-16} {1}", name, RecipeContext.Readable(New FileInfo(other).Length))
            Next
            context.Say("  {0,-16} {1}", "bundle.tar.zst", RecipeContext.Readable(New FileInfo(archivePath).Length))
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System.IO;
using Bastion.Archive.Formats.Tar;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Make and read a <c>.tar.zst</c>, the newest of the compressed tarballs.
    /// </summary>
    /// <remarks>
    /// This recipe used to demonstrate a refusal. Bastion.Archive decoded Zstandard without encoding it, so
    /// asking for a <c>.tar.zst</c> was refused <b>by name</b> rather than quietly given a different
    /// compressor. The Zstandard encoder was added later and the refusal went with it, so the recipe now does what the
    /// other three tarball recipes do — which is the point: a caller writes the name they want and the library
    /// works out the rest.
    /// <para>
    /// Zstandard is the one worth reaching for when the archive will be read more often than it is written.
    /// It decompresses several times faster than gzip at a better ratio, which is why it has become the
    /// default for container images and package managers.
    /// </para>
    /// </remarks>
    internal static class TarZstRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();

            var archivePath = context.PathTo("bundle.tar.zst");
            var created = TarArchive.CreateFromDirectory(source, archivePath);
            if (!created.Succeeded)
            {
                context.Say(created.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say("wrote {0} from {1} of files",
                RecipeContext.Readable(new FileInfo(archivePath).Length),
                RecipeContext.Readable(TarGzRecipe.SizeOf(source)));

            // The short spelling means the same thing here as it does for the others.
            var shortName = context.PathTo("bundle.tzst");
            var alsoCreated = TarArchive.CreateFromDirectory(source, shortName);
            if (!alsoCreated.Succeeded)
            {
                context.Say(alsoCreated.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say(".tzst is the same archive: {0}", RecipeContext.Readable(new FileInfo(shortName).Length));

            var target = context.PathTo("unpacked");
            var extracted = TarArchive.ExtractToDirectory(archivePath, target);
            if (!extracted.Succeeded)
            {
                context.Say(extracted.ToString());
                return RecipeOutcome.Failed;
            }

            if (!TarGzRecipe.SameTree(source, target, context)) return RecipeOutcome.Failed;
            context.Say("every file came back through the Zstandard decoder with the same bytes");

            // Against the other three, on the same files, so the choice can be made on numbers.
            foreach (var name in new[] { "bundle.tar.gz", "bundle.tar.bz2", "bundle.tar.xz" })
            {
                var other = context.PathTo(name);
                var made = TarArchive.CreateFromDirectory(source, other);
                if (!made.Succeeded)
                {
                    context.Say(made.ToString());
                    return RecipeOutcome.Failed;
                }

                context.Say("  {0,-16} {1}", name, RecipeContext.Readable(new FileInfo(other).Length));
            }

            context.Say("  {0,-16} {1}", "bundle.tar.zst", RecipeContext.Readable(new FileInfo(archivePath).Length));
            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Text
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Verify every checksum, and see a damaged one fail.
    ''' </summary>
    ''' <remarks>
    ''' <c>Test</c> reads every entry to the end and throws the data away, which is exactly what <c>7z t</c>
    ''' does: it verifies each CRC-32, and each authentication code on an encrypted entry, without writing
    ''' anything. This recipe then damages one byte of an entry's data and shows the test refusing the archive,
    ''' because a library that verifies checksums only when convenient is a library that hands you corrupt data.
    ''' </remarks>
    Friend Module TestArchiveRecipe

        Private Const Marker As String = "CHECKSUM-MARKER-FLIP-THIS-BYTE"

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim archivePath = context.PathTo("sound.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                ' Stored rather than deflated, so the marker is findable in the file and one flipped byte
                ' damages the data without disturbing any structure around it.
                Dim stored As New AdditionOptions() With {.Method = CompressionMethod.Store}
                Using payload As New MemoryStream(Encoding.ASCII.GetBytes(Marker & " " & New String("."c, 400)))
                    Dim added = writer.AddStream(payload, "marked.txt", stored)
                    If Not added.Succeeded Then
                        context.Say(added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                End Using
                Using other As New MemoryStream(RecipeContext.PseudoRandom(20000, 5))
                    Dim added = writer.AddStream(other, "noise.bin", Nothing)
                    If Not added.Succeeded Then
                        context.Say(added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                End Using
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim sound = Archive.Open(archivePath)
            If Not sound.Succeeded Then
                context.Say(sound.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = sound.Archive
                Dim tested = archive.Test(Nothing)
                If Not tested.Succeeded Then
                    context.Say("the sound archive should have passed: " & tested.ToString())
                    Return RecipeOutcome.Failed
                End If
                context.Say("sound archive: {0} entries verified in {1:N0} ms",
                            archive.Entries.Count, tested.Elapsed.TotalMilliseconds)
            End Using

            ' Damage a copy, never the original. One byte, inside the stored entry's own data.
            Dim damagedPath = context.PathTo("damaged.zip")
            Dim bytes = File.ReadAllBytes(archivePath)
            Dim offset = IndexOf(bytes, Encoding.ASCII.GetBytes(Marker))
            If offset < 0 Then
                context.Say("the marker was not found in the archive, so nothing was damaged")
                Return RecipeOutcome.Failed
            End If
            bytes(offset + 5) = CByte(bytes(offset + 5) Xor &H20)
            File.WriteAllBytes(damagedPath, bytes)
            context.Say("flipped one bit at offset {0}, inside the data of 'marked.txt'", offset + 5)

            Dim damaged = Archive.Open(damagedPath)
            If Not damaged.Succeeded Then
                context.Say("open refused the damaged archive with " & damaged.ErrorCode.ToString())
                Return RecipeOutcome.Passed
            End If
            Using archive = damaged.Archive
                Dim tested = archive.Test(Nothing)
                If tested.Succeeded Then
                    context.Say("the damaged archive passed the test, which it must not")
                    Return RecipeOutcome.Failed
                End If
                context.Say("damaged archive: {0} — {1}", tested.ErrorCode, tested.ErrorDescription)
                If tested.ErrorCode <> ErrorCode.ChecksumMismatch Then
                    context.Say("expected ChecksumMismatch for a flipped data byte")
                    Return RecipeOutcome.Failed
                End If
            End Using
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>Finds a byte sequence, which is all this recipe needs to know where to do its damage.</summary>
        Private Function IndexOf(haystack As Byte(), needle As Byte()) As Integer
            For start = 0 To haystack.Length - needle.Length
                Dim matched = True
                For index = 0 To needle.Length - 1
                    If haystack(start + index) <> needle(index) Then
                        matched = False
                        Exit For
                    End If
                Next
                If matched Then Return start
            Next
            Return -1
        End Function

    End Module

End Namespace

C#

using System.IO;
using System.Text;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Verify every checksum, and see a damaged one fail.
    /// </summary>
    /// <remarks>
    /// <c>Test</c> reads every entry to the end and throws the data away, which is exactly what <c>7z t</c>
    /// does: it verifies each CRC-32, and each authentication code on an encrypted entry, without writing
    /// anything. This recipe then damages one byte of an entry's data and shows the test refusing the archive,
    /// because a library that verifies checksums only when convenient is a library that hands you corrupt data.
    /// </remarks>
    internal static class TestArchiveRecipe
    {
        private const string Marker = "CHECKSUM-MARKER-FLIP-THIS-BYTE";

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var archivePath = context.PathTo("sound.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                // Stored rather than deflated, so the marker is findable in the file and one flipped byte
                // damages the data without disturbing any structure around it.
                var stored = new AdditionOptions { Method = CompressionMethod.Store };
                using (var payload = new MemoryStream(Encoding.ASCII.GetBytes(Marker + " " + new string('.', 400))))
                {
                    var added = writer.AddStream(payload, "marked.txt", stored);
                    if (!added.Succeeded)
                    {
                        context.Say(added.ToString());
                        return RecipeOutcome.Failed;
                    }
                }

                using (var other = new MemoryStream(RecipeContext.PseudoRandom(20000, 5)))
                {
                    var added = writer.AddStream(other, "noise.bin", null);
                    if (!added.Succeeded)
                    {
                        context.Say(added.ToString());
                        return RecipeOutcome.Failed;
                    }
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            var sound = Archive.Open(archivePath);
            if (!sound.Succeeded)
            {
                context.Say(sound.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = sound.Archive)
            {
                var tested = archive.Test(null);
                if (!tested.Succeeded)
                {
                    context.Say("the sound archive should have passed: " + tested);
                    return RecipeOutcome.Failed;
                }

                context.Say("sound archive: {0} entries verified in {1:N0} ms",
                    archive.Entries.Count, tested.Elapsed.TotalMilliseconds);
            }

            // Damage a copy, never the original. One byte, inside the stored entry's own data.
            var damagedPath = context.PathTo("damaged.zip");
            var bytes = File.ReadAllBytes(archivePath);
            var offset = IndexOf(bytes, Encoding.ASCII.GetBytes(Marker));
            if (offset < 0)
            {
                context.Say("the marker was not found in the archive, so nothing was damaged");
                return RecipeOutcome.Failed;
            }

            bytes[offset + 5] = (byte)(bytes[offset + 5] ^ 0x20);
            File.WriteAllBytes(damagedPath, bytes);
            context.Say("flipped one bit at offset {0}, inside the data of 'marked.txt'", offset + 5);

            var damaged = Archive.Open(damagedPath);
            if (!damaged.Succeeded)
            {
                context.Say("open refused the damaged archive with " + damaged.ErrorCode);
                return RecipeOutcome.Passed;
            }

            using (var archive = damaged.Archive)
            {
                var tested = archive.Test(null);
                if (tested.Succeeded)
                {
                    context.Say("the damaged archive passed the test, which it must not");
                    return RecipeOutcome.Failed;
                }

                context.Say("damaged archive: {0} — {1}", tested.ErrorCode, tested.ErrorDescription);
                if (tested.ErrorCode != ErrorCode.ChecksumMismatch)
                {
                    context.Say("expected ChecksumMismatch for a flipped data byte");
                    return RecipeOutcome.Failed;
                }
            }

            return RecipeOutcome.Passed;
        }

        /// <summary>Finds a byte sequence, which is all this recipe needs to know where to do its damage.</summary>
        private static int IndexOf(byte[] haystack, byte[] needle)
        {
            for (var start = 0; start <= haystack.Length - needle.Length; start++)
            {
                var matched = true;
                for (var index = 0; index < needle.Length; index++)
                {
                    if (haystack[start + index] != needle[index])
                    {
                        matched = false;
                        break;
                    }
                }

                if (matched) return start;
            }

            return -1;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Globalization
Imports System.IO
Imports System.Security.Cryptography
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Carry timestamps and attributes across, and write the same bytes twice.
    ''' </summary>
    ''' <remarks>
    ''' A ZIP entry's own timestamp field is a DOS date and time, which has two-second resolution and no time
    ''' zone at all. The library writes the NTFS extra field alongside it, so a modified time survives to
    ''' 100-nanosecond resolution in UTC, and falls back to the DOS field for a reader that does not know the
    ''' extra field. A timestamp that has to be truncated is reported as a warning rather than silently rounded.
    ''' The second half of this recipe is determinism. With
    ''' <see cref="TimestampMode.Fixed"/> and a stable entry order, the same input gives a byte-identical
    ''' archive — the same on .NET Framework 4.6 as on .NET 10, on one thread or several. That is what makes an
    ''' archive's SHA-256 something a build can publish, and it is impossible for any library that puts
    ''' <c>DateTime.Now</c> in the output.
    ''' </remarks>
    Friend Module TimestampsAndAttributesRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.PathTo("source")
            Directory.CreateDirectory(source)
            Dim readOnlyFile = Path.Combine(source, "fixed.txt")
            Dim ordinaryFile = Path.Combine(source, "ordinary.txt")
            File.WriteAllText(readOnlyFile, "This one is read-only and dated 1999.")
            File.WriteAllText(ordinaryFile, "This one is ordinary.")

            ' A time with an odd second and sub-second precision, which the DOS field alone cannot hold.
            Dim stamp = New DateTime(1999, 12, 31, 23, 59, 59, 123, DateTimeKind.Utc)
            File.SetLastWriteTimeUtc(readOnlyFile, stamp)
            File.SetAttributes(readOnlyFile, FileAttributes.ReadOnly)

            Dim archivePath = context.PathTo("metadata.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                For Each filePath In New String() {readOnlyFile, ordinaryFile}
                    Dim added = writer.AddFile(filePath, Path.GetFileName(filePath))
                    If Not added.Succeeded Then
                        context.Say(added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                Next
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                For Each entry In archive.Entries
                    context.Say("  {0}  modified {1}  attributes 0x{2:X2}",
                                entry.Name.PadRight(14),
                                entry.LastWriteUtc.ToString("yyyy-MM-dd HH:mm:ss.fff", CultureInfo.InvariantCulture),
                                entry.DosAttributes)
                Next

                Dim target = context.PathTo("out")
                Dim options As New ExtractionOptions() With {
                    .RestoreTimestamps = True,
                    .RestoreAttributes = True
                }
                Dim extracted = archive.ExtractAll(target, options)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                For Each warning In extracted.Warnings
                    context.Say("warning {0}: {1}", warning.Code, warning.Message)
                Next

                Dim producedPath = Path.Combine(target, "fixed.txt")
                Dim produced = File.GetLastWriteTimeUtc(producedPath)
                Dim drift = (produced - stamp).Duration()
                context.Say("the extracted file is dated {0}, {1:N0} ms from the original",
                            produced.ToString("yyyy-MM-dd HH:mm:ss.fff", CultureInfo.InvariantCulture),
                            drift.TotalMilliseconds)
                ' The NTFS extra field carries it exactly; two seconds is what the DOS field alone would cost.
                If drift > TimeSpan.FromSeconds(2) Then
                    context.Say("the timestamp did not survive")
                    Return RecipeOutcome.Failed
                End If
                Dim attributes = File.GetAttributes(producedPath)
                Dim isReadOnly = (attributes And FileAttributes.ReadOnly) <> 0
                context.Say("the read-only attribute {0}", If(isReadOnly, "came across", "did not come across"))
                If Not isReadOnly Then Return RecipeOutcome.Failed
                ' Leave it writable, so the scratch directory can be cleaned up afterwards.
                File.SetAttributes(producedPath, FileAttributes.Normal)
            End Using

            Return Determinism(context, source)
        End Function

        ''' <summary>
        ''' Writes the same tree twice with a fixed timestamp and compares the two archives by SHA-256.
        ''' </summary>
        Private Function Determinism(context As RecipeContext, source As String) As RecipeOutcome
            Dim settings As New CompressionSettings() With {
                .Timestamps = TimestampMode.Fixed,
                .FixedTimestampUtc = New DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc),
                .Ordering = EntryOrdering.OrdinalByPath,
                .Level = 6
            }

            Dim digests(1) As String
            For attempt = 0 To 1
                Dim archivePath = context.PathTo("deterministic-" & attempt.ToString(CultureInfo.InvariantCulture) & ".zip")
                Dim started = ArchiveWriter.Create(archivePath, settings)
                If Not started.Succeeded Then
                    context.Say(started.ToString())
                    Return RecipeOutcome.Failed
                End If
                Using writer = started.Writer
                    Dim added = writer.AddDirectory(source, Nothing, Nothing)
                    If Not added.Succeeded Then
                        context.Say(added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                    Dim finished = writer.Complete()
                    If Not finished.Succeeded Then
                        context.Say(finished.ToString())
                        Return RecipeOutcome.Failed
                    End If
                End Using
                digests(attempt) = Digest(archivePath)
            Next

            context.Say("first  SHA-256 {0}", digests(0))
            context.Say("second SHA-256 {0}", digests(1))
            If Not String.Equals(digests(0), digests(1), StringComparison.Ordinal) Then
                context.Say("the same input produced two different archives")
                Return RecipeOutcome.Failed
            End If
            context.Say("the same input produced the same bytes, which is what makes a digest publishable")
            Return RecipeOutcome.Passed
        End Function

        Private Function Digest(path As String) As String
            Using algorithm = SHA256.Create()
                Using stream As New FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read)
                    Dim hash = algorithm.ComputeHash(stream)
                    Dim builder As New System.Text.StringBuilder(hash.Length * 2)
                    For Each value In hash
                        builder.Append(value.ToString("x2", CultureInfo.InvariantCulture))
                    Next
                    Return builder.ToString()
                End Using
            End Using
        End Function

    End Module

End Namespace

C#

using System;
using System.Globalization;
using System.IO;
using System.Security.Cryptography;
using System.Text;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Carry timestamps and attributes across, and write the same bytes twice.
    /// </summary>
    /// <remarks>
    /// A ZIP entry's own timestamp field is a DOS date and time, which has two-second resolution and no time
    /// zone at all. The library writes the NTFS extra field alongside it, so a modified time survives to
    /// 100-nanosecond resolution in UTC, and falls back to the DOS field for a reader that does not know the
    /// extra field. A timestamp that has to be truncated is reported as a warning rather than silently rounded.
    /// The second half of this recipe is determinism. With
    /// <see cref="TimestampMode.Fixed"/> and a stable entry order, the same input gives a byte-identical
    /// archive — the same on .NET Framework 4.6 as on .NET 10, on one thread or several. That is what makes an
    /// archive's SHA-256 something a build can publish, and it is impossible for any library that puts
    /// <c>DateTime.Now</c> in the output.
    /// </remarks>
    internal static class TimestampsAndAttributesRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.PathTo("source");
            Directory.CreateDirectory(source);
            var readOnlyFile = Path.Combine(source, "fixed.txt");
            var ordinaryFile = Path.Combine(source, "ordinary.txt");
            File.WriteAllText(readOnlyFile, "This one is read-only and dated 1999.");
            File.WriteAllText(ordinaryFile, "This one is ordinary.");

            // A time with an odd second and sub-second precision, which the DOS field alone cannot hold.
            var stamp = new DateTime(1999, 12, 31, 23, 59, 59, 123, DateTimeKind.Utc);
            File.SetLastWriteTimeUtc(readOnlyFile, stamp);
            File.SetAttributes(readOnlyFile, FileAttributes.ReadOnly);

            var archivePath = context.PathTo("metadata.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                foreach (var filePath in new[] { readOnlyFile, ordinaryFile })
                {
                    var added = writer.AddFile(filePath, Path.GetFileName(filePath));
                    if (!added.Succeeded)
                    {
                        context.Say(added.ToString());
                        return RecipeOutcome.Failed;
                    }
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                foreach (var entry in archive.Entries)
                {
                    context.Say("  {0}  modified {1}  attributes 0x{2:X2}",
                        entry.Name.PadRight(14),
                        entry.LastWriteUtc.ToString("yyyy-MM-dd HH:mm:ss.fff", CultureInfo.InvariantCulture),
                        entry.DosAttributes);
                }

                var target = context.PathTo("out");
                var options = new ExtractionOptions { RestoreTimestamps = true, RestoreAttributes = true };
                var extracted = archive.ExtractAll(target, options);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                foreach (var warning in extracted.Warnings)
                {
                    context.Say("warning {0}: {1}", warning.Code, warning.Message);
                }

                var producedPath = Path.Combine(target, "fixed.txt");
                var produced = File.GetLastWriteTimeUtc(producedPath);
                var drift = (produced - stamp).Duration();
                context.Say("the extracted file is dated {0}, {1:N0} ms from the original",
                    produced.ToString("yyyy-MM-dd HH:mm:ss.fff", CultureInfo.InvariantCulture),
                    drift.TotalMilliseconds);
                // The NTFS extra field carries it exactly; two seconds is what the DOS field alone would cost.
                if (drift > TimeSpan.FromSeconds(2))
                {
                    context.Say("the timestamp did not survive");
                    return RecipeOutcome.Failed;
                }

                var attributes = File.GetAttributes(producedPath);
                var isReadOnly = (attributes & FileAttributes.ReadOnly) != 0;
                context.Say("the read-only attribute {0}", isReadOnly ? "came across" : "did not come across");
                if (!isReadOnly) return RecipeOutcome.Failed;
                // Leave it writable, so the scratch directory can be cleaned up afterwards.
                File.SetAttributes(producedPath, FileAttributes.Normal);
            }

            return Determinism(context, source);
        }

        /// <summary>
        /// Writes the same tree twice with a fixed timestamp and compares the two archives by SHA-256.
        /// </summary>
        private static RecipeOutcome Determinism(RecipeContext context, string source)
        {
            var settings = new CompressionSettings
            {
                Timestamps = TimestampMode.Fixed,
                FixedTimestampUtc = new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc),
                Ordering = EntryOrdering.OrdinalByPath,
                Level = 6
            };

            var digests = new string[2];
            for (var attempt = 0; attempt < 2; attempt++)
            {
                var archivePath = context.PathTo("deterministic-" + attempt.ToString(CultureInfo.InvariantCulture) + ".zip");
                var started = ArchiveWriter.Create(archivePath, settings);
                if (!started.Succeeded)
                {
                    context.Say(started.ToString());
                    return RecipeOutcome.Failed;
                }

                using (var writer = started.Writer)
                {
                    var added = writer.AddDirectory(source, null, null);
                    if (!added.Succeeded)
                    {
                        context.Say(added.ToString());
                        return RecipeOutcome.Failed;
                    }

                    var finished = writer.Complete();
                    if (!finished.Succeeded)
                    {
                        context.Say(finished.ToString());
                        return RecipeOutcome.Failed;
                    }
                }

                digests[attempt] = Digest(archivePath);
            }

            context.Say("first  SHA-256 {0}", digests[0]);
            context.Say("second SHA-256 {0}", digests[1]);
            if (!string.Equals(digests[0], digests[1], StringComparison.Ordinal))
            {
                context.Say("the same input produced two different archives");
                return RecipeOutcome.Failed;
            }

            context.Say("the same input produced the same bytes, which is what makes a digest publishable");
            return RecipeOutcome.Passed;
        }

        private static string Digest(string path)
        {
            using (var algorithm = SHA256.Create())
            {
                using (var stream = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read))
                {
                    var hash = algorithm.ComputeHash(stream);
                    var builder = new StringBuilder(hash.Length * 2);
                    foreach (var value in hash)
                    {
                        builder.Append(value.ToString("x2", CultureInfo.InvariantCulture));
                    }

                    return builder.ToString();
                }
            }
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Globalization
Imports System.IO
Imports System.Text
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Keep non-ASCII entry names exactly as they were given.
    ''' </summary>
    ''' <remarks>
    ''' The format's own name encoding is IBM code page 437, which has no room for most of the world. The way
    ''' out is general purpose bit 11, the "language encoding flag": set it and the name is UTF-8. This library
    ''' sets it for any name that needs it and leaves it clear for a name that does not, so an ASCII archive
    ''' stays byte-identical to what an old tool would have written.
    ''' Reading is the harder half, because an archive written by an old tool has no flag and no declaration.
    ''' <c>ArchiveOpenOptions.FallbackCodePage</c> is what says "treat unflagged names as code page 932", which
    ''' is the only honest answer: the information is not in the file, so it has to come from the caller.
    ''' Names are compared and printed here by code point rather than by eye, because whether a console can
    ''' render an emoji says nothing about whether the archive is right.
    ''' </remarks>
    Friend Module UnicodeNamesRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            ' Latin with diacritics, Greek, Cyrillic, Japanese, an emoji outside the basic plane, and one
            ' plain ASCII name to show that the flag is set per entry rather than per archive.
            Dim names = New String() {
                "documents/résumé-außergewöhnlich.txt",
                "documents/Ελληνικά.txt",
                "документы/отчёт.txt",
                "書類/報告書.txt",
                "emoji/" & Char.ConvertFromUtf32(&H1F4E6) & "-parcel.txt",
                "plain-ascii.txt"
            }

            Dim archivePath = context.PathTo("unicode.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                For index = 0 To names.Length - 1
                    Dim body = Encoding.UTF8.GetBytes("This entry is named " & names(index))
                    Using source As New MemoryStream(body, False)
                        Dim added = writer.AddStream(source, names(index), Nothing)
                        If Not added.Succeeded Then
                            context.Say(added.ToString())
                            Return RecipeOutcome.Failed
                        End If
                    End Using
                Next
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                If archive.Entries.Count <> names.Length Then
                    context.Say("{0} entries went in and {1} came back", names.Length, archive.Entries.Count)
                    Return RecipeOutcome.Failed
                End If
                For index = 0 To names.Length - 1
                    Dim recovered = archive.Entries(index).Name
                    context.Say("  {0}  {1}", If(String.Equals(recovered, names(index), StringComparison.Ordinal), "same", "DIFFERENT"),
                                Describe(recovered))
                    If Not String.Equals(recovered, names(index), StringComparison.Ordinal) Then
                        context.Say("    went in as " & Describe(names(index)))
                        Return RecipeOutcome.Failed
                    End If
                Next

                ' The names have to work as paths too, which is a separate question from surviving the format.
                Dim target = context.PathTo("out")
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim produced = Directory.GetFiles(target, "*", SearchOption.AllDirectories)
                context.Say("{0} files extracted with their names intact", produced.Length)
                If produced.Length <> names.Length Then Return RecipeOutcome.Failed
                For Each name In names
                    Dim expected = Path.Combine(target, name.Replace("/"c, Path.DirectorySeparatorChar))
                    If Not File.Exists(expected) Then
                        context.Say("not on disk under the name it was given: " & Describe(name))
                        Return RecipeOutcome.Failed
                    End If
                Next
            End Using
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>
        ''' A name written so it can be compared on any console: printable ASCII as itself, everything else as
        ''' its code unit. Whether a terminal can draw a character is not the archive's problem.
        ''' </summary>
        Private Function Describe(name As String) As String
            Dim builder As New StringBuilder(name.Length + 16)
            For Each character In name
                Dim code = Convert.ToInt32(character)
                If code >= &H20 AndAlso code < &H7F Then
                    builder.Append(character)
                Else
                    builder.Append(String.Format(CultureInfo.InvariantCulture, "\u{0:X4}", code))
                End If
            Next
            Return builder.ToString()
        End Function

    End Module

End Namespace

C#

using System;
using System.Globalization;
using System.IO;
using System.Text;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Keep non-ASCII entry names exactly as they were given.
    /// </summary>
    /// <remarks>
    /// The format's own name encoding is IBM code page 437, which has no room for most of the world. The way
    /// out is general purpose bit 11, the "language encoding flag": set it and the name is UTF-8. This library
    /// sets it for any name that needs it and leaves it clear for a name that does not, so an ASCII archive
    /// stays byte-identical to what an old tool would have written.
    /// Reading is the harder half, because an archive written by an old tool has no flag and no declaration.
    /// <c>ArchiveOpenOptions.FallbackCodePage</c> is what says "treat unflagged names as code page 932", which
    /// is the only honest answer: the information is not in the file, so it has to come from the caller.
    /// Names are compared and printed here by code point rather than by eye, because whether a console can
    /// render an emoji says nothing about whether the archive is right.
    /// </remarks>
    internal static class UnicodeNamesRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            // Latin with diacritics, Greek, Cyrillic, Japanese, an emoji outside the basic plane, and one
            // plain ASCII name to show that the flag is set per entry rather than per archive.
            var names = new[]
            {
                "documents/résumé-außergewöhnlich.txt",
                "documents/Ελληνικά.txt",
                "документы/отчёт.txt",
                "書類/報告書.txt",
                "emoji/" + char.ConvertFromUtf32(0x1F4E6) + "-parcel.txt",
                "plain-ascii.txt"
            };

            var archivePath = context.PathTo("unicode.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                foreach (var name in names)
                {
                    var body = Encoding.UTF8.GetBytes("This entry is named " + name);
                    using (var source = new MemoryStream(body, false))
                    {
                        var added = writer.AddStream(source, name, null);
                        if (!added.Succeeded)
                        {
                            context.Say(added.ToString());
                            return RecipeOutcome.Failed;
                        }
                    }
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                if (archive.Entries.Count != names.Length)
                {
                    context.Say("{0} entries went in and {1} came back", names.Length, archive.Entries.Count);
                    return RecipeOutcome.Failed;
                }

                for (var index = 0; index < names.Length; index++)
                {
                    var recovered = archive.Entries[index].Name;
                    var same = string.Equals(recovered, names[index], StringComparison.Ordinal);
                    context.Say("  {0}  {1}", same ? "same" : "DIFFERENT", Describe(recovered));
                    if (!same)
                    {
                        context.Say("    went in as " + Describe(names[index]));
                        return RecipeOutcome.Failed;
                    }
                }

                // The names have to work as paths too, which is a separate question from surviving the format.
                var target = context.PathTo("out");
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                var produced = Directory.GetFiles(target, "*", SearchOption.AllDirectories);
                context.Say("{0} files extracted with their names intact", produced.Length);
                if (produced.Length != names.Length) return RecipeOutcome.Failed;
                foreach (var name in names)
                {
                    var expected = Path.Combine(target, name.Replace('/', Path.DirectorySeparatorChar));
                    if (!File.Exists(expected))
                    {
                        context.Say("not on disk under the name it was given: " + Describe(name));
                        return RecipeOutcome.Failed;
                    }
                }
            }

            return RecipeOutcome.Passed;
        }

        /// <summary>
        /// A name written so it can be compared on any console: printable ASCII as itself, everything else as
        /// its code unit. Whether a terminal can draw a character is not the archive's problem.
        /// </summary>
        private static string Describe(string name)
        {
            var builder = new StringBuilder(name.Length + 16);
            foreach (var character in name)
            {
                var code = Convert.ToInt32(character);
                if (code >= 0x20 && code < 0x7F)
                {
                    builder.Append(character);
                }
                else
                {
                    builder.Append(string.Format(CultureInfo.InvariantCulture, "\\u{0:X4}", code));
                }
            }

            return builder.ToString();
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Add, rename and remove by rebuilding into a new file.
    ''' </summary>
    ''' <remarks>
    ''' There is no in-place update, on purpose. An <see cref="ArchiveUpdate"/> describes
    ''' what should change and <c>Apply</c> writes a new archive; the source is opened read-only and comes out
    ''' byte for byte identical. What that buys is that a power cut during an update costs you the update rather
    ''' than the archive.
    ''' An entry the update does not touch is copied across still compressed and still encrypted — never
    ''' decoded and re-encoded — so renaming one file in a large archive costs a file copy, not a recompression.
    ''' A replacement keeps the position the original held, so an update does not reshuffle an archive.
    ''' </remarks>
    Friend Module UpdateArchiveRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim archivePath = context.PathTo("original.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, Nothing, Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim before = File.ReadAllBytes(archivePath)
            Dim newFile = context.PathTo("licence.txt")
            File.WriteAllText(newFile, "Bastion Software Solutions Ltd — sample licence text.")

            Dim update As New ArchiveUpdate(archivePath)
            update.Remove("data.bin")
            update.Rename("readme.txt", "docs/readme.txt")
            update.AddOrReplaceFile(newFile, "licence.txt")
            update.AddOrReplaceDirectory("docs/")

            Dim targetPath = context.PathTo("updated.zip")
            Dim applied = update.Apply(targetPath, Nothing)
            If Not applied.Succeeded Then
                context.Say(applied.ToString())
                Return RecipeOutcome.Failed
            End If
            context.Say("rebuilt in {0:N0} ms", applied.Elapsed.TotalMilliseconds)

            ' The source is untouched. This is the claim worth checking, so it is checked rather than asserted.
            If Not RecipeContext.SameBytes(before, File.ReadAllBytes(archivePath)) Then
                context.Say("the source archive changed, which it must never do")
                Return RecipeOutcome.Failed
            End If
            context.Say("the source archive is byte for byte what it was")

            ' Applying over an existing file is refused, like every other write.
            Dim refused = update.Apply(targetPath, Nothing)
            If refused.Succeeded Then
                context.Say("applying over an existing file should have been refused")
                Return RecipeOutcome.Failed
            End If
            context.Say("applying over an existing file returned " & refused.ErrorCode.ToString())

            Dim opened = Archive.Open(targetPath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim hasRemoved = False
                Dim hasRenamed = False
                Dim hasAdded = False
                For Each entry In archive.Entries
                    If String.Equals(entry.Name, "data.bin", StringComparison.Ordinal) Then hasRemoved = True
                    If String.Equals(entry.Name, "docs/readme.txt", StringComparison.Ordinal) Then hasRenamed = True
                    If String.Equals(entry.Name, "licence.txt", StringComparison.Ordinal) Then hasAdded = True
                Next
                context.Say("{0} entries: removed={1} renamed={2} added={3}",
                            archive.Entries.Count, Not hasRemoved, hasRenamed, hasAdded)
                If hasRemoved OrElse Not hasRenamed OrElse Not hasAdded Then Return RecipeOutcome.Failed

                Dim target = context.PathTo("out")
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim carried = File.ReadAllText(Path.Combine(target, "docs", "readme.txt"))
                context.Say("the renamed entry still reads: " & carried)
                If carried.Length = 0 Then Return RecipeOutcome.Failed
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Add, rename and remove by rebuilding into a new file.
    /// </summary>
    /// <remarks>
    /// There is no in-place update, on purpose. An <see cref="ArchiveUpdate"/> describes
    /// what should change and <c>Apply</c> writes a new archive; the source is opened read-only and comes out
    /// byte for byte identical. What that buys is that a power cut during an update costs you the update rather
    /// than the archive.
    /// An entry the update does not touch is copied across still compressed and still encrypted — never
    /// decoded and re-encoded — so renaming one file in a large archive costs a file copy, not a recompression.
    /// A replacement keeps the position the original held, so an update does not reshuffle an archive.
    /// </remarks>
    internal static class UpdateArchiveRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var archivePath = context.PathTo("original.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, null, null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return RecipeOutcome.Failed;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            var before = File.ReadAllBytes(archivePath);
            var newFile = context.PathTo("licence.txt");
            File.WriteAllText(newFile, "Bastion Software Solutions Ltd — sample licence text.");

            var update = new ArchiveUpdate(archivePath);
            update.Remove("data.bin");
            update.Rename("readme.txt", "docs/readme.txt");
            update.AddOrReplaceFile(newFile, "licence.txt");
            update.AddOrReplaceDirectory("docs/");

            var targetPath = context.PathTo("updated.zip");
            var applied = update.Apply(targetPath, null);
            if (!applied.Succeeded)
            {
                context.Say(applied.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say("rebuilt in {0:N0} ms", applied.Elapsed.TotalMilliseconds);

            // The source is untouched. This is the claim worth checking, so it is checked rather than asserted.
            if (!RecipeContext.SameBytes(before, File.ReadAllBytes(archivePath)))
            {
                context.Say("the source archive changed, which it must never do");
                return RecipeOutcome.Failed;
            }

            context.Say("the source archive is byte for byte what it was");

            // Applying over an existing file is refused, like every other write.
            var refused = update.Apply(targetPath, null);
            if (refused.Succeeded)
            {
                context.Say("applying over an existing file should have been refused");
                return RecipeOutcome.Failed;
            }

            context.Say("applying over an existing file returned " + refused.ErrorCode);

            var opened = Archive.Open(targetPath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var hasRemoved = false;
                var hasRenamed = false;
                var hasAdded = false;
                foreach (var entry in archive.Entries)
                {
                    if (string.Equals(entry.Name, "data.bin", StringComparison.Ordinal)) hasRemoved = true;
                    if (string.Equals(entry.Name, "docs/readme.txt", StringComparison.Ordinal)) hasRenamed = true;
                    if (string.Equals(entry.Name, "licence.txt", StringComparison.Ordinal)) hasAdded = true;
                }

                context.Say("{0} entries: removed={1} renamed={2} added={3}",
                    archive.Entries.Count, !hasRemoved, hasRenamed, hasAdded);
                if (hasRemoved || !hasRenamed || !hasAdded) return RecipeOutcome.Failed;

                var target = context.PathTo("out");
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                var carried = File.ReadAllText(Path.Combine(target, "docs", "readme.txt"));
                context.Say("the renamed entry still reads: " + carried);
                if (carried.Length == 0) return RecipeOutcome.Failed;
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Write a Windows image (<c>.wim</c>) and read it back, then read one Microsoft made.
    ''' </summary>
    ''' <remarks>
    ''' A path ending <c>.wim</c> writes a one-image WIM with every resource stored, as 7-Zip writes it. WIM keeps
    ''' each distinct content once, found by its SHA-1, so ten copies of a file cost one — the recipe shows it by
    ''' writing the sample tree twice over and comparing sizes. Reading is the same <c>Archive.Open</c> as for any
    ''' other format, and Windows ships a WIM compressed with XPRESS in System32 that serves as a second example.
    ''' </remarks>
    Friend Module WimCreateRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            Dim once = Write(context, "once.wim", source, 1)
            Dim twice = Write(context, "twice.wim", source, 2)
            If once < 0 OrElse twice < 0 Then Return RecipeOutcome.Failed
            context.Say("the tree once: {0}; twice over: {1} — the second copy costs only its directory entries",
                        RecipeContext.Readable(once), RecipeContext.Readable(twice))
            If twice - once > 4096 Then Return RecipeOutcome.Failed

            Dim opened = Archive.Open(context.PathTo("twice.wim"))
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                context.Say("opened as {0} with {1} entries", archive.Format, archive.Entries.Count)
                Dim target = context.PathTo("unpacked")
                Dim extracted = archive.ExtractAll(target)
                If Not extracted.Succeeded Then
                    context.Say(extracted.ToString())
                    Return RecipeOutcome.Failed
                End If
                If Not SevenZipCreateRecipe.SameTree(source, Path.Combine(target, "copy2"), context) Then Return RecipeOutcome.Failed
            End Using

            ' Microsoft's own WIM, on Windows: XPRESS-compressed, read by the library's own decoder.
            Dim shipped = Path.Combine(Environment.SystemDirectory, "DrtmAuthTxt.wim")
            If File.Exists(shipped) Then
                Dim theirs = Archive.Open(shipped)
                If Not theirs.Succeeded Then
                    context.Say(theirs.ToString())
                    Return RecipeOutcome.Failed
                End If
                Using archive = theirs.Archive
                    Dim tested = archive.Test(Nothing)
                    context.Say("{0}: {1} entries, method {2}, test {3}", Path.GetFileName(shipped), archive.Entries.Count,
                                archive.Entries(archive.Entries.Count - 1).Method, tested.ErrorCode)
                    If Not tested.Succeeded Then Return RecipeOutcome.Failed
                End Using
            End If
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>Writes the tree <paramref name="copies"/> times over into one WIM and returns its size, or -1.</summary>
        Private Function Write(context As RecipeContext, name As String, source As String, copies As Integer) As Long
            Dim path = context.PathTo(name)
            Dim started = ArchiveWriter.Create(path)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return -1
            End If
            Using writer = started.Writer
                For copy = 1 To copies
                    Dim added = writer.AddDirectory(source, "copy" & copy, Nothing)
                    If Not added.Succeeded Then
                        context.Say(added.ToString())
                        Return -1
                    End If
                Next
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return -1
                End If
            End Using
            Return New FileInfo(path).Length
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Write a Windows image (<c>.wim</c>) and read it back, then read one Microsoft made.
    /// </summary>
    /// <remarks>
    /// A path ending <c>.wim</c> writes a one-image WIM with every resource stored, as 7-Zip writes it. WIM keeps
    /// each distinct content once, found by its SHA-1, so ten copies of a file cost one — the recipe shows it by
    /// writing the sample tree twice over and comparing sizes. Reading is the same <c>Archive.Open</c> as for any
    /// other format, and Windows ships a WIM compressed with XPRESS in System32 that serves as a second example.
    /// </remarks>
    internal static class WimCreateRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            var once = Write(context, "once.wim", source, 1);
            var twice = Write(context, "twice.wim", source, 2);
            if (once < 0 || twice < 0) return RecipeOutcome.Failed;
            context.Say("the tree once: {0}; twice over: {1} — the second copy costs only its directory entries",
                RecipeContext.Readable(once), RecipeContext.Readable(twice));
            if (twice - once > 4096) return RecipeOutcome.Failed;

            var opened = Archive.Open(context.PathTo("twice.wim"));
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                context.Say("opened as {0} with {1} entries", archive.Format, archive.Entries.Count);
                var target = context.PathTo("unpacked");
                var extracted = archive.ExtractAll(target);
                if (!extracted.Succeeded)
                {
                    context.Say(extracted.ToString());
                    return RecipeOutcome.Failed;
                }

                if (!SevenZipCreateRecipe.SameTree(source, Path.Combine(target, "copy2"), context)) return RecipeOutcome.Failed;
            }

            // Microsoft's own WIM, on Windows: XPRESS-compressed, read by the library's own decoder.
            var shipped = Path.Combine(Environment.SystemDirectory, "DrtmAuthTxt.wim");
            if (File.Exists(shipped))
            {
                var theirs = Archive.Open(shipped);
                if (!theirs.Succeeded)
                {
                    context.Say(theirs.ToString());
                    return RecipeOutcome.Failed;
                }

                using (var archive = theirs.Archive)
                {
                    var tested = archive.Test(null);
                    context.Say("{0}: {1} entries, method {2}, test {3}", Path.GetFileName(shipped), archive.Entries.Count,
                        archive.Entries[archive.Entries.Count - 1].Method, tested.ErrorCode);
                    if (!tested.Succeeded) return RecipeOutcome.Failed;
                }
            }

            return RecipeOutcome.Passed;
        }

        /// <summary>Writes the tree <paramref name="copies"/> times over into one WIM and returns its size, or -1.</summary>
        private static long Write(RecipeContext context, string name, string source, int copies)
        {
            var path = context.PathTo(name);
            var started = ArchiveWriter.Create(path);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return -1;
            }

            using (var writer = started.Writer)
            {
                for (var copy = 1; copy <= copies; copy++)
                {
                    var added = writer.AddDirectory(source, "copy" + copy, null);
                    if (!added.Succeeded)
                    {
                        context.Say(added.ToString());
                        return -1;
                    }
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return -1;
                }
            }

            return new FileInfo(path).Length;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Linq
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Read the two things a WIM records that no other format here does: each file's Windows security descriptor,
    ''' and its NTFS alternate data streams.
    ''' </summary>
    ''' <remarks>
    ''' <c>ArchiveEntry.GetSecurityDescriptor()</c> hands back the self-relative <c>SECURITY_DESCRIPTOR</c> the
    ''' image stored, in the form <c>SetFileSecurity</c> takes — this library does not interpret it, and returns a
    ''' fresh copy each call. An alternate data stream is an entry of its own named <c>file:stream</c>, marked by
    ''' <c>IsAlternateStream</c>; it can be read like any other entry, and <c>ExtractAll</c> skips it with a warning
    ''' rather than writing it, because a stream can only be written beside a file that already exists.
    ''' <para>
    ''' The WIM Windows ships in System32 carries a descriptor for every one of its files, so this recipe needs no
    ''' producer of its own; where it is not present, the recipe says so instead of pretending.
    ''' </para>
    ''' </remarks>
    Friend Module WimSecurityRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim shipped = Path.Combine(Environment.SystemDirectory, "DrtmAuthTxt.wim")
            If Not File.Exists(shipped) Then
                context.Say("{0} is not on this machine, so there is no WIM here carrying security descriptors.", shipped)
                Return RecipeOutcome.Passed
            End If

            Dim opened = Archive.Open(shipped)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim secured = archive.Entries.Where(Function(e) e.GetSecurityDescriptor() IsNot Nothing).ToArray()
                context.Say("{0} of {1} entries carry a security descriptor", secured.Length, archive.Entries.Count)
                If secured.Length = 0 Then
                    context.Say("this image was written without them; nothing further to show.")
                    Return RecipeOutcome.Passed
                End If

                Dim descriptor = secured(0).GetSecurityDescriptor()
                ' Byte 0 is the revision, always 1; bit 0x80 of byte 3 is SE_SELF_RELATIVE, which says the four
                ' offsets that follow are offsets into these same bytes rather than pointers.
                context.Say("'{0}': {1} bytes, revision {2}, self-relative {3}",
                            secured(0).Name, descriptor.Length, descriptor(0), (descriptor(3) And &H80) <> 0)
                If descriptor(0) <> 1 Then Return RecipeOutcome.Failed
                ' On Windows the bytes go straight to the API: new RawSecurityDescriptor(descriptor, 0) reads it,
                ' and File.SetAccessControl applies it. Nothing here needs a reference to do that.

                Dim streams = archive.Entries.Where(Function(e) e.IsAlternateStream).ToArray()
                If streams.Length = 0 Then
                    context.Say("no alternate data streams in this image — 7z a -twim -sns writes one that looks like 'readme.txt:meta'")
                Else
                    For Each stream In streams
                        Using content As New MemoryStream()
                            Dim read = archive.ExtractToStream(stream, content, Nothing)
                            If Not read.Succeeded Then
                                context.Say(read.ToString())
                                Return RecipeOutcome.Failed
                            End If
                            context.Say("stream '{0}': {1} bytes read", stream.Name, content.Length)
                        End Using
                    Next
                End If
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;
using System.Linq;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Read the two things a WIM records that no other format here does: each file's Windows security descriptor,
    /// and its NTFS alternate data streams.
    /// </summary>
    /// <remarks>
    /// <c>ArchiveEntry.GetSecurityDescriptor()</c> hands back the self-relative <c>SECURITY_DESCRIPTOR</c> the
    /// image stored, in the form <c>SetFileSecurity</c> takes — this library does not interpret it, and returns a
    /// fresh copy each call. An alternate data stream is an entry of its own named <c>file:stream</c>, marked by
    /// <c>IsAlternateStream</c>; it can be read like any other entry, and <c>ExtractAll</c> skips it with a warning
    /// rather than writing it, because a stream can only be written beside a file that already exists.
    /// <para>
    /// The WIM Windows ships in System32 carries a descriptor for every one of its files, so this recipe needs no
    /// producer of its own; where it is not present, the recipe says so instead of pretending.
    /// </para>
    /// </remarks>
    internal static class WimSecurityRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var shipped = Path.Combine(Environment.SystemDirectory, "DrtmAuthTxt.wim");
            if (!File.Exists(shipped))
            {
                context.Say("{0} is not on this machine, so there is no WIM here carrying security descriptors.", shipped);
                return RecipeOutcome.Passed;
            }

            var opened = Archive.Open(shipped);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var secured = archive.Entries.Where(e => e.GetSecurityDescriptor() != null).ToArray();
                context.Say("{0} of {1} entries carry a security descriptor", secured.Length, archive.Entries.Count);
                if (secured.Length == 0)
                {
                    context.Say("this image was written without them; nothing further to show.");
                    return RecipeOutcome.Passed;
                }

                var descriptor = secured[0].GetSecurityDescriptor();
                // Byte 0 is the revision, always 1; bit 0x80 of byte 3 is SE_SELF_RELATIVE, which says the four
                // offsets that follow are offsets into these same bytes rather than pointers.
                context.Say("'{0}': {1} bytes, revision {2}, self-relative {3}",
                    secured[0].Name, descriptor.Length, descriptor[0], (descriptor[3] & 0x80) != 0);
                if (descriptor[0] != 1) return RecipeOutcome.Failed;
                // On Windows the bytes go straight to the API: new RawSecurityDescriptor(descriptor, 0) reads it,
                // and File.SetAccessControl applies it. Nothing here needs a reference to do that.

                var streams = archive.Entries.Where(e => e.IsAlternateStream).ToArray();
                if (streams.Length == 0)
                {
                    context.Say("no alternate data streams in this image — 7z a -twim -sns writes one that looks like 'readme.txt:meta'");
                }
                else
                {
                    foreach (var stream in streams)
                    {
                        using (var content = new MemoryStream())
                        {
                            var read = archive.ExtractToStream(stream, content, null);
                            if (!read.Succeeded)
                            {
                                context.Say(read.ToString());
                                return RecipeOutcome.Failed;
                            }

                            context.Say("stream '{0}': {1} bytes read", stream.Name, content.Length);
                        }
                    }
                }
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Text
Imports Bastion.Archive
Imports Bastion.Archive.Formats.Xz

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Write an <c>.xz</c> file in blocks, then jump straight to the middle of it.
    ''' </summary>
    ''' <remarks>
    ''' xz is the format that learned from gzip and bzip2, and blocks are what it learned. A file written in
    ''' blocks carries an index of them at the end, and the index is what turns a compressed file into one you
    ''' can read from the middle: a seek costs **one block**, not one file.
    ''' <para>
    ''' That is reached through the ordinary <see cref="System.IO.Stream"/> contract rather than an API of its
    ''' own. <c>CanSeek</c> becomes true when the source can seek and the index can be read,
    ''' and then <c>Position</c>, <c>Seek</c> and <c>Length</c> do what they do anywhere else — so a caller
    ''' who wants the tenth megabyte writes <c>Position = 10485760</c> and never learns that this format has an
    ''' index. A file written as one block seeks no faster than it reads, which is the writer's choice; a
    ''' source that cannot seek, such as a pipe, stays forward-only rather than failing to open.
    ''' </para>
    ''' </remarks>
    Friend Module XzStreamUsageRecipe

        ''' <summary>A megabyte and a half, so several blocks are worth having.</summary>
        Private Const ContentLength As Integer = 1500000

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim content = Patterned(ContentLength)
            Dim archivePath = context.PathTo("payload.xz")

            Dim blocks As Integer
            Using file As New FileStream(archivePath, FileMode.Create, FileAccess.Write)
                ' Level 6, a CRC-64 after every block, and a block every 256 KiB.
                Dim writer As New XzEncoderStream(file, 6, XzCheck.Crc64, 262144L, leaveOpen:=True)
                Try
                    writer.Write(content, 0, content.Length)
                Finally
                    writer.Dispose()
                End Try
                ' Asked after disposing, not before: the last block is short and is not written until the
                ' stream is finished, so a count taken inside the block is one too few.
                blocks = writer.BlockCount
            End Using
            context.Say("{0} in, {1} out, in {2} blocks with a CRC-64 each",
                        RecipeContext.Readable(content.Length),
                        RecipeContext.Readable(New FileInfo(archivePath).Length), blocks)

            Using file As New FileStream(archivePath, FileMode.Open, FileAccess.Read)
                Using reader As New XzDecoderStream(file, leaveOpen:=True)
                    Using produced As New MemoryStream()
                        GZipStreamUsageRecipe.CopyAll(reader, produced)
                        If Not RecipeContext.SameBytes(content, produced.ToArray()) Then
                            context.Say("the bytes that came back are not the bytes that went in")
                            Return RecipeOutcome.Failed
                        End If
                        context.Say("read back whole: {0} blocks, check {1}", reader.BlockCount, reader.Check)
                    End Using
                End Using
            End Using

            Using file As New FileStream(archivePath, FileMode.Open, FileAccess.Read)
                Using reader As New XzDecoderStream(file, leaveOpen:=True)
                    If Not reader.CanSeek Then
                        context.Say("this file has no readable index, so it can only be read forwards")
                        Return RecipeOutcome.Failed
                    End If
                    context.Say("the index says the content is {0}", RecipeContext.Readable(reader.Length))

                    ' Offsets in no particular order, including one backwards, because that is the case a
                    ' forward-only reader cannot do at all.
                    For Each at In New Long() {1200000L, 300000L, 262144L, 262143L, 0L}
                        reader.Position = at
                        Dim window(63) As Byte
                        Dim filled = 0
                        Do While filled < window.Length
                            Dim taken = reader.Read(window, filled, window.Length - filled)
                            If taken <= 0 Then Exit Do
                            filled += taken
                        Loop
                        For index = 0 To filled - 1
                            If content(CInt(at) + index) <> window(index) Then
                                context.Say("seeking to {0} gave the wrong byte at {1}", at, index)
                                Return RecipeOutcome.Failed
                            End If
                        Next
                    Next
                    context.Say("five seeks, forwards and back, every byte where it should be")
                End Using
            End Using

            Return RecipeOutcome.Passed
        End Function

        ''' <summary>
        ''' Content that compresses well and is still different everywhere, so a seek landing in the wrong
        ''' place is caught rather than matching by luck.
        ''' </summary>
        Private Function Patterned(length As Integer) As Byte()
            Dim builder As New StringBuilder(length + 64)
            Dim line = 0
            Do While builder.Length < length
                builder.Append("line ")
                builder.Append(line.ToString(Globalization.CultureInfo.InvariantCulture))
                builder.Append(": the quick brown fox jumps over the lazy dog")
                builder.Append(Environment.NewLine)
                line += 1
            Loop
            Dim all = Encoding.ASCII.GetBytes(builder.ToString())
            Dim result(length - 1) As Byte
            System.Buffer.BlockCopy(all, 0, result, 0, length)
            Return result
        End Function

    End Module

End Namespace

C#

using System;
using System.Globalization;
using System.IO;
using System.Text;
using Bastion.Archive.Formats.Xz;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Write an <c>.xz</c> file in blocks, then jump straight to the middle of it.
    /// </summary>
    /// <remarks>
    /// xz is the format that learned from gzip and bzip2, and blocks are what it learned. A file written in
    /// blocks carries an index of them at the end, and the index is what turns a compressed file into one you
    /// can read from the middle: a seek costs <b>one block</b>, not one file.
    /// <para>
    /// That is reached through the ordinary <see cref="Stream"/> contract rather than an API of its own
    ///. <c>CanSeek</c> becomes true when the source can seek and the index can be read, and
    /// then <c>Position</c>, <c>Seek</c> and <c>Length</c> do what they do anywhere else — so a caller who
    /// wants the tenth megabyte writes <c>Position = 10485760</c> and never learns that this format has an
    /// index. A file written as one block seeks no faster than it reads, which is the writer's choice; a
    /// source that cannot seek, such as a pipe, stays forward-only rather than failing to open.
    /// </para>
    /// </remarks>
    internal static class XzStreamUsageRecipe
    {
        /// <summary>A megabyte and a half, so several blocks are worth having.</summary>
        private const int ContentLength = 1500000;

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var content = Patterned(ContentLength);
            var archivePath = context.PathTo("payload.xz");

            int blocks;
            using (var file = new FileStream(archivePath, FileMode.Create, FileAccess.Write))
            {
                // Level 6, a CRC-64 after every block, and a block every 256 KiB.
                var writer = new XzEncoderStream(file, 6, XzCheck.Crc64, 262144L, leaveOpen: true);
                try
                {
                    writer.Write(content, 0, content.Length);
                }
                finally
                {
                    writer.Dispose();
                }

                // Asked after disposing, not before: the last block is short and is not written until the
                // stream is finished, so a count taken inside the block is one too few.
                blocks = writer.BlockCount;
            }

            context.Say("{0} in, {1} out, in {2} blocks with a CRC-64 each",
                RecipeContext.Readable(content.Length),
                RecipeContext.Readable(new FileInfo(archivePath).Length), blocks);

            using (var file = new FileStream(archivePath, FileMode.Open, FileAccess.Read))
            using (var reader = new XzDecoderStream(file, leaveOpen: true))
            using (var produced = new MemoryStream())
            {
                GZipStreamUsageRecipe.CopyAll(reader, produced);
                if (!RecipeContext.SameBytes(content, produced.ToArray()))
                {
                    context.Say("the bytes that came back are not the bytes that went in");
                    return RecipeOutcome.Failed;
                }

                context.Say("read back whole: {0} blocks, check {1}", reader.BlockCount, reader.Check);
            }

            using (var file = new FileStream(archivePath, FileMode.Open, FileAccess.Read))
            using (var reader = new XzDecoderStream(file, leaveOpen: true))
            {
                if (!reader.CanSeek)
                {
                    context.Say("this file has no readable index, so it can only be read forwards");
                    return RecipeOutcome.Failed;
                }

                context.Say("the index says the content is {0}", RecipeContext.Readable(reader.Length));

                // Offsets in no particular order, including one backwards, because that is the case a
                // forward-only reader cannot do at all.
                foreach (var at in new[] { 1200000L, 300000L, 262144L, 262143L, 0L })
                {
                    reader.Position = at;
                    var window = new byte[64];
                    var filled = 0;
                    while (filled < window.Length)
                    {
                        var taken = reader.Read(window, filled, window.Length - filled);
                        if (taken <= 0) break;
                        filled += taken;
                    }

                    for (var index = 0; index < filled; index++)
                    {
                        if (content[(int)at + index] != window[index])
                        {
                            context.Say("seeking to {0} gave the wrong byte at {1}", at, index);
                            return RecipeOutcome.Failed;
                        }
                    }
                }

                context.Say("five seeks, forwards and back, every byte where it should be");
            }

            return RecipeOutcome.Passed;
        }

        /// <summary>
        /// Content that compresses well and is still different everywhere, so a seek landing in the wrong
        /// place is caught rather than matching by luck.
        /// </summary>
        private static byte[] Patterned(int length)
        {
            var builder = new StringBuilder(length + 64);
            var line = 0;
            while (builder.Length < length)
            {
                builder.Append("line ");
                builder.Append(line.ToString(CultureInfo.InvariantCulture));
                builder.Append(": the quick brown fox jumps over the lazy dog");
                builder.Append(Environment.NewLine);
                line++;
            }

            var all = Encoding.ASCII.GetBytes(builder.ToString());
            var result = new byte[length];
            Buffer.BlockCopy(all, 0, result, 0, length);
            return result;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.Globalization
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Cross the four-gibibyte line that needs Zip64.
    ''' </summary>
    ''' <remarks>
    ''' The original ZIP record layout holds a size in 32 bits, so 4 GiB − 1 is the largest entry it can
    ''' describe. Zip64 adds 64-bit sizes in an extra field, and the value <c>0xFFFFFFFF</c> in the old field is
    ''' what redirects a reader to it. That last detail is the one everybody gets wrong: <c>0xFFFFFFFF</c> is a
    ''' <em>reserved redirection</em>, not a size, so an entry of exactly 4 294 967 295 bytes needs Zip64 too.
    ''' Every comparison in this library is therefore <c>&gt;=</c> rather than <c>&gt;</c>, and the four-case
    ''' boundary fixture in the test suite exists because the first version of that code used <c>&gt;</c> and
    ''' produced an archive no reader could open.
    ''' Nothing has to be switched on. The writer uses Zip64 for an entry that needs it and not for one that
    ''' does not, so an ordinary archive stays readable by an ordinary reader.
    ''' </remarks>
    Friend Module Zip64LargeFileRecipe

        ''' <summary>One byte past the largest size the 32-bit fields can describe.</summary>
        Private Const OverTheLine As Long = 4294967296L + 1024L

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            If Not context.IsFullRun Then
                context.Say("skipped: proving this needs an entry of at least {0}, which takes minutes and",
                            RecipeContext.Readable(4294967295L))
                context.Say("several gibibytes of scratch disk. Run 'ArchiveCookbook Zip64LargeFile --full' for the")
                context.Say("real thing. The boundary is covered on every build by Zip64BoundaryTests, which")
                context.Say("checks 4 GiB - 1, 4 GiB, 4 GiB + 1 and the 0xFFFFFFFF sentinel itself, and by the")
                context.Say("Size=Large oracle fixtures that hand the result to the 7-Zip command line.")
                Return RecipeOutcome.Skipped
            End If

            Dim archivePath = context.PathTo("large.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If

            context.Say("writing one entry of {0} ({1:N0} bytes) — this is the slow part",
                        RecipeContext.Readable(OverTheLine), OverTheLine)
            Dim lastReport = DateTime.UtcNow
            Using writer = started.Writer
                AddHandler writer.Monitor.Progress,
                    Sub(sender, e)
                        If (DateTime.UtcNow - lastReport).TotalSeconds < 15 Then Return
                        lastReport = DateTime.UtcNow
                        context.Say("  {0:N1}% — {1}", e.TotalPercent, RecipeContext.Readable(e.ProcessedBytes))
                    End Sub

                ' A generated stream, so nothing this large is ever written to disk uncompressed. It reports its
                ' own Length, which is how the writer knows at the time it writes the local header that this
                ' entry needs Zip64 sizes in it.
                Using source As New RepeatingStream(OverTheLine)
                    Dim added = writer.AddStream(source, "large.bin", Nothing)
                    If Not added.Succeeded Then
                        context.Say(added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                End Using
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using
            context.Say("the archive itself is {0} on disk", RecipeContext.Readable(New FileInfo(archivePath).Length))

            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim entry = archive.Entries(0)
                context.Say("read back: {0}, {1:N0} bytes", entry.Name, entry.Size)
                If entry.Size <> OverTheLine Then
                    context.Say("the size did not survive the round trip")
                    Return RecipeOutcome.Failed
                End If
                ' Verifying it means reading all of it and checking the CRC, which Test does without writing.
                Dim tested = archive.Test(Nothing)
                If Not tested.Succeeded Then
                    context.Say(tested.ToString())
                    Return RecipeOutcome.Failed
                End If
                context.Say("verified in {0:N0} s", tested.Elapsed.TotalSeconds)
            End Using
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>
        ''' A read-only stream of a fixed length that produces a repeating pattern. It exists so a recipe can
        ''' hand the writer several gibibytes without any of them existing anywhere.
        ''' </summary>
        Private NotInheritable Class RepeatingStream
            Inherits Stream

            Private ReadOnly _pattern As Byte()
            Private ReadOnly _length As Long
            Private _position As Long

            Public Sub New(length As Long)
                If length < 0 Then Throw New ArgumentOutOfRangeException(NameOf(length))
                _length = length
                ' Compressible, but not a single byte repeated: a run of zeros would say nothing about the
                ' encoder, and this is still small enough that the archive stays a few megabytes.
                _pattern = RecipeContext.PseudoRandom(4096, 31)
            End Sub

            Public Overrides ReadOnly Property CanRead As Boolean
                Get
                    Return True
                End Get
            End Property

            Public Overrides ReadOnly Property CanSeek As Boolean
                Get
                    Return True
                End Get
            End Property

            Public Overrides ReadOnly Property CanWrite As Boolean
                Get
                    Return False
                End Get
            End Property

            Public Overrides ReadOnly Property Length As Long
                Get
                    Return _length
                End Get
            End Property

            Public Overrides Property Position As Long
                Get
                    Return _position
                End Get
                Set(value As Long)
                    If value < 0 Then Throw New ArgumentOutOfRangeException(NameOf(value))
                    _position = value
                End Set
            End Property

            Public Overrides Function Read(buffer As Byte(), offset As Integer, count As Integer) As Integer
                If buffer Is Nothing Then Throw New ArgumentNullException(NameOf(buffer))
                Dim remaining = _length - _position
                If remaining <= 0 Then Return 0
                Dim taken = CInt(Math.Min(CLng(count), remaining))
                For index = 0 To taken - 1
                    buffer(offset + index) = _pattern(CInt((_position + index) Mod _pattern.Length))
                Next
                _position += taken
                Return taken
            End Function

            Public Overrides Function Seek(offset As Long, origin As SeekOrigin) As Long
                Select Case origin
                    Case SeekOrigin.Begin
                        Position = offset
                    Case SeekOrigin.Current
                        Position = _position + offset
                    Case Else
                        Position = _length + offset
                End Select
                Return _position
            End Function

            Public Overrides Sub Flush()
            End Sub

            Public Overrides Sub SetLength(value As Long)
                Throw New NotSupportedException("This stream is read-only.")
            End Sub

            Public Overrides Sub Write(buffer As Byte(), offset As Integer, count As Integer)
                Throw New NotSupportedException("This stream is read-only.")
            End Sub

        End Class

    End Module

End Namespace

C#

using System;
using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Cross the four-gibibyte line that needs Zip64.
    /// </summary>
    /// <remarks>
    /// The original ZIP record layout holds a size in 32 bits, so 4 GiB − 1 is the largest entry it can
    /// describe. Zip64 adds 64-bit sizes in an extra field, and the value <c>0xFFFFFFFF</c> in the old field is
    /// what redirects a reader to it. That last detail is the one everybody gets wrong: <c>0xFFFFFFFF</c> is a
    /// <em>reserved redirection</em>, not a size, so an entry of exactly 4 294 967 295 bytes needs Zip64 too.
    /// Every comparison in this library is therefore <c>&gt;=</c> rather than <c>&gt;</c>, and the four-case
    /// boundary fixture in the test suite exists because the first version of that code used <c>&gt;</c> and
    /// produced an archive no reader could open.
    /// Nothing has to be switched on. The writer uses Zip64 for an entry that needs it and not for one that
    /// does not, so an ordinary archive stays readable by an ordinary reader.
    /// </remarks>
    internal static class Zip64LargeFileRecipe
    {
        /// <summary>One kibibyte past the largest size the 32-bit fields can describe.</summary>
        private const long OverTheLine = 4294967296L + 1024L;

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            if (!context.IsFullRun)
            {
                context.Say("skipped: proving this needs an entry of at least {0}, which takes minutes and",
                    RecipeContext.Readable(4294967295L));
                context.Say("several gibibytes of scratch disk. Run 'ArchiveCookbookCs Zip64LargeFile --full' for");
                context.Say("the real thing. The boundary is covered on every build by Zip64BoundaryTests, which");
                context.Say("checks 4 GiB - 1, 4 GiB, 4 GiB + 1 and the 0xFFFFFFFF sentinel itself, and by the");
                context.Say("Size=Large oracle fixtures that hand the result to the 7-Zip command line.");
                return RecipeOutcome.Skipped;
            }

            var archivePath = context.PathTo("large.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            context.Say("writing one entry of {0} ({1:N0} bytes) — this is the slow part",
                RecipeContext.Readable(OverTheLine), OverTheLine);
            var lastReport = DateTime.UtcNow;
            using (var writer = started.Writer)
            {
                writer.Monitor.Progress += (sender, e) =>
                {
                    if ((DateTime.UtcNow - lastReport).TotalSeconds < 15) return;
                    lastReport = DateTime.UtcNow;
                    context.Say("  {0:N1}% — {1}", e.TotalPercent, RecipeContext.Readable(e.ProcessedBytes));
                };

                // A generated stream, so nothing this large is ever written to disk uncompressed. It reports its
                // own Length, which is how the writer knows at the time it writes the local header that this
                // entry needs Zip64 sizes in it.
                using (var source = new RepeatingStream(OverTheLine))
                {
                    var added = writer.AddStream(source, "large.bin", null);
                    if (!added.Succeeded)
                    {
                        context.Say(added.ToString());
                        return RecipeOutcome.Failed;
                    }
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            context.Say("the archive itself is {0} on disk", RecipeContext.Readable(new FileInfo(archivePath).Length));

            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var entry = archive.Entries[0];
                context.Say("read back: {0}, {1:N0} bytes", entry.Name, entry.Size);
                if (entry.Size != OverTheLine)
                {
                    context.Say("the size did not survive the round trip");
                    return RecipeOutcome.Failed;
                }

                // Verifying it means reading all of it and checking the CRC, which Test does without writing.
                var tested = archive.Test(null);
                if (!tested.Succeeded)
                {
                    context.Say(tested.ToString());
                    return RecipeOutcome.Failed;
                }

                context.Say("verified in {0:N0} s", tested.Elapsed.TotalSeconds);
            }

            return RecipeOutcome.Passed;
        }

        /// <summary>
        /// A read-only stream of a fixed length that produces a repeating pattern. It exists so a recipe can
        /// hand the writer several gibibytes without any of them existing anywhere.
        /// </summary>
        private sealed class RepeatingStream : Stream
        {
            private readonly byte[] _pattern;
            private readonly long _length;
            private long _position;

            public RepeatingStream(long length)
            {
                if (length < 0) throw new ArgumentOutOfRangeException(nameof(length));
                _length = length;
                // Compressible, but not a single byte repeated: a run of zeros would say nothing about the
                // encoder, and this is still small enough that the archive stays a few megabytes.
                _pattern = RecipeContext.PseudoRandom(4096, 31);
            }

            public override bool CanRead => true;

            public override bool CanSeek => true;

            public override bool CanWrite => false;

            public override long Length => _length;

            public override long Position
            {
                get { return _position; }
                set
                {
                    if (value < 0) throw new ArgumentOutOfRangeException(nameof(value));
                    _position = value;
                }
            }

            public override int Read(byte[] buffer, int offset, int count)
            {
                if (buffer == null) throw new ArgumentNullException(nameof(buffer));
                var remaining = _length - _position;
                if (remaining <= 0) return 0;
                var taken = (int)Math.Min(count, remaining);
                for (var index = 0; index < taken; index++)
                {
                    buffer[offset + index] = _pattern[(int)((_position + index) % _pattern.Length)];
                }

                _position += taken;
                return taken;
            }

            public override long Seek(long offset, SeekOrigin origin)
            {
                switch (origin)
                {
                    case SeekOrigin.Begin:
                        Position = offset;
                        break;
                    case SeekOrigin.Current:
                        Position = _position + offset;
                        break;
                    default:
                        Position = _length + offset;
                        break;
                }

                return _position;
            }

            public override void Flush()
            {
            }

            public override void SetLength(long value)
            {
                throw new NotSupportedException("This stream is read-only.");
            }

            public override void Write(byte[] buffer, int offset, int count)
            {
                throw new NotSupportedException("This stream is read-only.");
            }
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System.Globalization
Imports System.IO
Imports Bastion.Archive
Imports Bastion.Archive.Security

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Stop a decompression bomb with a total-byte budget.
    ''' </summary>
    ''' <remarks>
    ''' The guards are on by default and are the caller's to tighten: total bytes produced, entry count, ratio,
    ''' nesting depth and path length all live on <see cref="ExtractionPolicy"/>.
    ''' Which guard matters is worth understanding, because the obvious one is the weaker one. A ratio limit
    ''' cannot catch an honest Deflate stream at all: RFC 1951 caps a single stream at about 1032:1, and eight
    ''' mebibytes of zeros only reaches about 840:1, well under the 100 000:1 default. What a ratio limit
    ''' catches is a producer <em>lying</em> in the header about how much data is coming. The guard that stops a
    ''' large honest entry, or a thousand of them, is the total-byte budget — which is why this recipe sets that
    ''' one, and why the default is 1 TiB rather than unlimited.
    ''' The quoted-overlap bombs of the Fifield class are refused earlier still, at open time: every quoted copy
    ''' has to point at a local header bearing another entry's name, and the reader cross-checks the two.
    ''' </remarks>
    Friend Module ZipBombGuardRecipe

        ''' <summary>Eight mebibytes of zeros, which Deflate takes down to a few kilobytes.</summary>
        Private Const PayloadSize As Integer = 8 * 1024 * 1024

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim archivePath = context.PathTo("compressible.zip")
            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Dim payload(PayloadSize - 1) As Byte
            Using writer = started.Writer
                For index = 0 To 3
                    Using source As New MemoryStream(payload, False)
                        Dim added = writer.AddStream(source, "zeros-" & index.ToString("D2", CultureInfo.InvariantCulture) & ".bin", Nothing)
                        If Not added.Succeeded Then
                            context.Say(added.ToString())
                            Return RecipeOutcome.Failed
                        End If
                    End Using
                Next
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim archiveSize = New FileInfo(archivePath).Length
            Dim declared = 4L * PayloadSize
            context.Say("{0} on disk claims to hold {1} — a ratio of about {2:N0}:1",
                        RecipeContext.Readable(archiveSize), RecipeContext.Readable(declared), declared \ archiveSize)

            ' A budget of 10 MiB against 32 MiB of content: the extraction stops rather than filling the disk.
            Dim frugal As New ExtractionOptions()
            frugal.Policy.MaxTotalBytes = 10L * 1024L * 1024L
            frugal.Policy.Overwrite = OverwriteMode.Overwrite
            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim target = context.PathTo("out-budgeted")
                Dim stopped = archive.ExtractAll(target, frugal)
                If stopped.Succeeded Then
                    context.Say("a 10 MiB budget should not have extracted 32 MiB")
                    Return RecipeOutcome.Failed
                End If
                context.Say("with a 10 MiB budget: {0} — {1}", stopped.ErrorCode, stopped.ErrorDescription)
                If stopped.ErrorCode <> ErrorCode.LimitExceeded Then
                    context.Say("expected LimitExceeded")
                    Return RecipeOutcome.Failed
                End If
                Dim produced = 0L
                If Directory.Exists(target) Then
                    For Each filePath In Directory.GetFiles(target, "*", SearchOption.AllDirectories)
                        produced += New FileInfo(filePath).Length
                    Next
                End If
                context.Say("it stopped after producing {0}, not {1}",
                            RecipeContext.Readable(produced), RecipeContext.Readable(declared))
                If produced > frugal.Policy.MaxTotalBytes Then
                    context.Say("more was written than the budget allowed")
                    Return RecipeOutcome.Failed
                End If

                ' An entry-count limit is the same idea for an archive with a million tiny files.
                Dim fewEntries As New ExtractionOptions()
                fewEntries.Policy.MaxEntryCount = 2
                fewEntries.Policy.Overwrite = OverwriteMode.Overwrite
                Dim refused = archive.ExtractAll(context.PathTo("out-counted"), fewEntries)
                If refused.Succeeded Then
                    context.Say("an entry limit of 2 should not have extracted 4 entries")
                    Return RecipeOutcome.Failed
                End If
                context.Say("with an entry limit of 2: {0}", refused.ErrorCode)

                ' With a budget that fits, the same archive extracts normally: the guard is a limit, not a veto.
                Dim generous As New ExtractionOptions()
                generous.Policy.MaxTotalBytes = 64L * 1024L * 1024L
                Dim allowed = archive.ExtractAll(context.PathTo("out-allowed"), generous)
                If Not allowed.Succeeded Then
                    context.Say(allowed.ToString())
                    Return RecipeOutcome.Failed
                End If
                context.Say("with a 64 MiB budget the same archive extracted in {0:N0} ms",
                            allowed.Elapsed.TotalMilliseconds)
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System.Globalization;
using System.IO;
using Bastion.Archive.Security;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Stop a decompression bomb with a total-byte budget.
    /// </summary>
    /// <remarks>
    /// The guards are on by default and are the caller's to tighten: total bytes produced, entry count, ratio,
    /// nesting depth and path length all live on <see cref="ExtractionPolicy"/>.
    /// Which guard matters is worth understanding, because the obvious one is the weaker one. A ratio limit
    /// cannot catch an honest Deflate stream at all: RFC 1951 caps a single stream at about 1032:1, and eight
    /// mebibytes of zeros only reaches about 840:1, well under the 100 000:1 default. What a ratio limit
    /// catches is a producer <em>lying</em> in the header about how much data is coming. The guard that stops a
    /// large honest entry, or a thousand of them, is the total-byte budget — which is why this recipe sets that
    /// one, and why the default is 1 TiB rather than unlimited.
    /// The quoted-overlap bombs of the Fifield class are refused earlier still, at open time: every quoted copy
    /// has to point at a local header bearing another entry's name, and the reader cross-checks the two.
    /// </remarks>
    internal static class ZipBombGuardRecipe
    {
        /// <summary>Eight mebibytes of zeros, which Deflate takes down to a few kilobytes.</summary>
        private const int PayloadSize = 8 * 1024 * 1024;

        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var archivePath = context.PathTo("compressible.zip");
            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            var payload = new byte[PayloadSize];
            using (var writer = started.Writer)
            {
                for (var index = 0; index < 4; index++)
                {
                    using (var source = new MemoryStream(payload, false))
                    {
                        var name = "zeros-" + index.ToString("D2", CultureInfo.InvariantCulture) + ".bin";
                        var added = writer.AddStream(source, name, null);
                        if (!added.Succeeded)
                        {
                            context.Say(added.ToString());
                            return RecipeOutcome.Failed;
                        }
                    }
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            var archiveSize = new FileInfo(archivePath).Length;
            var declared = 4L * PayloadSize;
            context.Say("{0} on disk claims to hold {1} — a ratio of about {2:N0}:1",
                RecipeContext.Readable(archiveSize), RecipeContext.Readable(declared), declared / archiveSize);

            // A budget of 10 MiB against 32 MiB of content: the extraction stops rather than filling the disk.
            var frugal = new ExtractionOptions();
            frugal.Policy.MaxTotalBytes = 10L * 1024L * 1024L;
            frugal.Policy.Overwrite = OverwriteMode.Overwrite;
            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var target = context.PathTo("out-budgeted");
                var stopped = archive.ExtractAll(target, frugal);
                if (stopped.Succeeded)
                {
                    context.Say("a 10 MiB budget should not have extracted 32 MiB");
                    return RecipeOutcome.Failed;
                }

                context.Say("with a 10 MiB budget: {0} — {1}", stopped.ErrorCode, stopped.ErrorDescription);
                if (stopped.ErrorCode != ErrorCode.LimitExceeded)
                {
                    context.Say("expected LimitExceeded");
                    return RecipeOutcome.Failed;
                }

                var produced = 0L;
                if (Directory.Exists(target))
                {
                    foreach (var filePath in Directory.GetFiles(target, "*", SearchOption.AllDirectories))
                    {
                        produced += new FileInfo(filePath).Length;
                    }
                }

                context.Say("it stopped after producing {0}, not {1}",
                    RecipeContext.Readable(produced), RecipeContext.Readable(declared));
                if (produced > frugal.Policy.MaxTotalBytes)
                {
                    context.Say("more was written than the budget allowed");
                    return RecipeOutcome.Failed;
                }

                // An entry-count limit is the same idea for an archive with a million tiny files.
                var fewEntries = new ExtractionOptions();
                fewEntries.Policy.MaxEntryCount = 2;
                fewEntries.Policy.Overwrite = OverwriteMode.Overwrite;
                var refused = archive.ExtractAll(context.PathTo("out-counted"), fewEntries);
                if (refused.Succeeded)
                {
                    context.Say("an entry limit of 2 should not have extracted 4 entries");
                    return RecipeOutcome.Failed;
                }

                context.Say("with an entry limit of 2: {0}", refused.ErrorCode);

                // With a budget that fits, the same archive extracts normally: the guard is a limit, not a veto.
                var generous = new ExtractionOptions();
                generous.Policy.MaxTotalBytes = 64L * 1024L * 1024L;
                var allowed = archive.ExtractAll(context.PathTo("out-allowed"), generous);
                if (!allowed.Succeeded)
                {
                    context.Say(allowed.ToString());
                    return RecipeOutcome.Failed;
                }

                context.Say("with a 64 MiB budget the same archive extracted in {0:N0} ms",
                    allowed.Elapsed.TotalMilliseconds);
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Add a whole directory tree under a prefix.
    ''' </summary>
    ''' <remarks>
    ''' <c>AddDirectory</c> walks the tree in a stable order, so the same tree gives the same archive on every
    ''' framework and every operating system. The names it writes use forward slashes, whatever
    ''' the platform's separator is, because that is what the format says and what every other reader expects.
    ''' A filter is a plain <c>Func(Of String, Boolean)</c> over the relative path, which is enough to express
    ''' "no logs", "only source" or an entire include/exclude language of the caller's own.
    ''' </remarks>
    Friend Module ZipFolderRecursiveRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            ' Two files the filter should leave out, one of them inside a subdirectory.
            File.WriteAllText(Path.Combine(source, "build.log"), "noise")
            File.WriteAllText(Path.Combine(source, "documents", "notes.log"), "more noise")

            Dim archivePath = context.PathTo("tree.zip")
            Dim options As New AdditionOptions() With {
                .Recursive = True,
                .IncludeDirectoryEntries = True,
                .Filter = Function(relative) Not relative.EndsWith(".log", StringComparison.OrdinalIgnoreCase)
            }

            Dim started = ArchiveWriter.Create(archivePath)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return RecipeOutcome.Failed
            End If
            Using writer = started.Writer
                ' The prefix is how a tree lands inside a folder in the archive rather than at its root.
                Dim added = writer.AddDirectory(source, "project", options)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return RecipeOutcome.Failed
                End If
            End Using

            Dim opened = Archive.Open(archivePath)
            If Not opened.Succeeded Then
                context.Say(opened.ToString())
                Return RecipeOutcome.Failed
            End If
            Using archive = opened.Archive
                Dim directories = 0
                For Each entry In archive.Entries
                    context.Say("  {0}{1}", entry.Name, If(entry.IsDirectory, "  (directory entry)", ""))
                    If entry.IsDirectory Then directories += 1
                    If Not entry.Name.StartsWith("project/", StringComparison.Ordinal) Then
                        context.Say("an entry escaped the prefix: " & entry.Name)
                        Return RecipeOutcome.Failed
                    End If
                    If entry.Name.IndexOf("\"c) >= 0 Then
                        context.Say("a backslash reached the archive: " & entry.Name)
                        Return RecipeOutcome.Failed
                    End If
                    If entry.Name.EndsWith(".log", StringComparison.OrdinalIgnoreCase) Then
                        context.Say("the filter let a log file through: " & entry.Name)
                        Return RecipeOutcome.Failed
                    End If
                Next
                If directories = 0 Then
                    context.Say("no directory entry was written, so an empty folder would not survive")
                    Return RecipeOutcome.Failed
                End If
                context.Say("{0} entries, {1} of them directories, all under 'project/'", archive.Entries.Count, directories)
            End Using
            Return RecipeOutcome.Passed
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Add a whole directory tree under a prefix.
    /// </summary>
    /// <remarks>
    /// <c>AddDirectory</c> walks the tree in a stable order, so the same tree gives the same archive on every
    /// framework and every operating system. The names it writes use forward slashes, whatever
    /// the platform's separator is, because that is what the format says and what every other reader expects.
    /// A filter is a plain <c>Func&lt;string, bool&gt;</c> over the relative path, which is enough to express
    /// "no logs", "only source" or an entire include/exclude language of the caller's own.
    /// </remarks>
    internal static class ZipFolderRecursiveRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            // Two files the filter should leave out, one of them inside a subdirectory.
            File.WriteAllText(Path.Combine(source, "build.log"), "noise");
            File.WriteAllText(Path.Combine(source, "documents", "notes.log"), "more noise");

            var archivePath = context.PathTo("tree.zip");
            var options = new AdditionOptions
            {
                Recursive = true,
                IncludeDirectoryEntries = true,
                Filter = relative => !relative.EndsWith(".log", StringComparison.OrdinalIgnoreCase)
            };

            var started = ArchiveWriter.Create(archivePath);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return RecipeOutcome.Failed;
            }

            using (var writer = started.Writer)
            {
                // The prefix is how a tree lands inside a folder in the archive rather than at its root.
                var added = writer.AddDirectory(source, "project", options);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return RecipeOutcome.Failed;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return RecipeOutcome.Failed;
                }
            }

            var opened = Archive.Open(archivePath);
            if (!opened.Succeeded)
            {
                context.Say(opened.ToString());
                return RecipeOutcome.Failed;
            }

            using (var archive = opened.Archive)
            {
                var directories = 0;
                foreach (var entry in archive.Entries)
                {
                    context.Say("  {0}{1}", entry.Name, entry.IsDirectory ? "  (directory entry)" : "");
                    if (entry.IsDirectory) directories++;
                    if (!entry.Name.StartsWith("project/", StringComparison.Ordinal))
                    {
                        context.Say("an entry escaped the prefix: " + entry.Name);
                        return RecipeOutcome.Failed;
                    }

                    if (entry.Name.IndexOf('\\') >= 0)
                    {
                        context.Say("a backslash reached the archive: " + entry.Name);
                        return RecipeOutcome.Failed;
                    }

                    if (entry.Name.EndsWith(".log", StringComparison.OrdinalIgnoreCase))
                    {
                        context.Say("the filter let a log file through: " + entry.Name);
                        return RecipeOutcome.Failed;
                    }
                }

                if (directories == 0)
                {
                    context.Say("no directory entry was written, so an empty folder would not survive");
                    return RecipeOutcome.Failed;
                }

                context.Say("{0} entries, {1} of them directories, all under 'project/'", archive.Entries.Count, directories);
            }

            return RecipeOutcome.Passed;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports Bastion.Archive

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Write the same files with bzip2, LZMA and XZ, and see what each one costs.
    ''' </summary>
    ''' <remarks>
    ''' Deflate is what every ZIP reader implements and what this library writes unless told otherwise. The
    ''' later methods — bzip2 (12), LZMA (14) and XZ (95) — compress better, sometimes much better, at the price
    ''' of a reader that has to implement them. A store-and-Deflate reader will open such an archive, list its
    ''' entries and then fail to extract them, which is a worse experience than being refused outright.
    ''' That is what WinZip's <c>.zipx</c> extension is for, and
    ''' <see cref="CompressionSettings.RecommendedFileExtension"/> says which name a given set of settings calls
    ''' for. The extension changes nothing inside the archive: the bytes are a ZIP either way and each entry's
    ''' header carries its method as always. The writer also reports the choice as an interoperability warning,
    ''' so a caller who did not think about it finds out anyway.
    ''' Which to pick depends on the data, and this recipe prints the evidence rather than asserting a ranking.
    ''' On the documentation-like prose it generates, bzip2 wins comfortably — a block sort suits text with
    ''' little long-range structure, and the reference bzip2 and LZMA rank the same way round on these bytes —
    ''' while LZMA and XZ come in a little under Deflate. On a source tree or a log file the order is usually
    ''' the other way about, which is the point: measure your own data.
    ''' One thing worth knowing about the levels. From five up the encoder chooses what to emit by **price**,
    ''' pricing every candidate through the range coder and taking the cheapest path; below five it takes the
    ''' longest match it can find, which is about six times faster and, on prose, some forty per cent worse.
    ''' 7-Zip draws the line in the same place.
    ''' </remarks>
    Friend Module ZipxMethodsRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim source = context.CreateSampleTree()
            ' A quarter of a mebibyte of prose, because on a handful of small files the per-entry overhead of
            ' the later methods swamps what they save and the comparison says nothing. This is the size at
            ' which the choice starts to matter.
            File.WriteAllBytes(Path.Combine(source, "manual.txt"), Prose(256 * 1024))
            Dim expected = File.ReadAllBytes(Path.Combine(source, "manual.txt"))

            ' Deflate first, as the baseline every reader can manage.
            Dim baseline = WriteWith(context, source, CompressionMethod.Deflate, "baseline")
            If baseline < 0 Then Return RecipeOutcome.Failed
            context.Say("Deflate: {0:N0} bytes, recommended name .zip", baseline)

            For Each method In New CompressionMethod() {CompressionMethod.BZip2, CompressionMethod.Lzma,
                                                        CompressionMethod.Xz}
                Dim settings As New CompressionSettings() With {.Method = method, .Level = 9}
                ' The name the convention calls for, which is advice rather than something done behind the
                ' caller's back: this recipe uses it to name the file.
                Dim extension = settings.RecommendedFileExtension
                If extension <> ".zipx" Then
                    context.Say("{0} should recommend .zipx, not {1}", method, extension)
                    Return RecipeOutcome.Failed
                End If
                Dim archivePath = context.PathTo(method.ToString().ToLowerInvariant() & extension)

                Dim started = ArchiveWriter.Create(archivePath, settings)
                If Not started.Succeeded Then
                    context.Say(started.ToString())
                    Return RecipeOutcome.Failed
                End If
                Dim warned = False
                Using writer = started.Writer
                    Dim added = writer.AddDirectory(source, Nothing, Nothing)
                    If Not added.Succeeded Then
                        context.Say(added.ToString())
                        Return RecipeOutcome.Failed
                    End If
                    Dim finished = writer.Complete()
                    If Not finished.Succeeded Then
                        context.Say(finished.ToString())
                        Return RecipeOutcome.Failed
                    End If
                    For Each warning In writer.InteropWarnings
                        If warning.Feature.IndexOf(".zipx", StringComparison.Ordinal) >= 0 Then warned = True
                    Next
                End Using
                If Not warned Then
                    context.Say("{0} should have reported the naming convention as an interoperability warning", method)
                    Return RecipeOutcome.Failed
                End If

                ' And it has to read back, which is the only claim that matters.
                Dim opened = Archive.Open(archivePath)
                If Not opened.Succeeded Then
                    context.Say(opened.ToString())
                    Return RecipeOutcome.Failed
                End If
                Using archive = opened.Archive
                    Dim target = context.PathTo("out-" & method.ToString())
                    Dim extracted = archive.ExtractAll(target)
                    If Not extracted.Succeeded Then
                        context.Say(extracted.ToString())
                        Return RecipeOutcome.Failed
                    End If
                    Dim recovered = File.ReadAllBytes(Path.Combine(target, "manual.txt"))
                    If Not RecipeContext.SameBytes(expected, recovered) Then
                        context.Say("{0} did not give back what it was given", method)
                        Return RecipeOutcome.Failed
                    End If
                End Using

                Dim size = New FileInfo(archivePath).Length
                context.Say("{0}: {1:N0} bytes ({2:P0} of Deflate), read back byte for byte, named {3}",
                            method, size, size / CDbl(baseline), Path.GetFileName(archivePath))
            Next
            Return RecipeOutcome.Passed
        End Function

        ''' <summary>
        ''' Prose of about the given length: sentences drawn from a small vocabulary, which compresses the way
        ''' documentation does rather than the way a single repeated byte does.
        ''' </summary>
        Private Function Prose(length As Integer) As Byte()
            Dim words = New String() {"archive", "entry", "method", "deflate", "dictionary", "window", "match",
                                      "literal", "checksum", "header", "volume", "stream", "reader", "writer",
                                      "compressed", "uncompressed", "the", "a", "and", "of", "that", "which"}
            Dim random As New Random(20260911)
            Dim builder As New System.Text.StringBuilder(length + 64)
            While builder.Length < length
                Dim wordsInSentence = 6 + random.Next(12)
                For index = 0 To wordsInSentence - 1
                    If index > 0 Then builder.Append(" "c)
                    builder.Append(words(random.Next(words.Length)))
                Next
                builder.Append(". ")
                If random.Next(6) = 0 Then builder.Append(Environment.NewLine)
            End While
            Return System.Text.Encoding.UTF8.GetBytes(builder.ToString().Substring(0, length))
        End Function

        ''' <summary>Writes the tree with one method and returns the archive's size, or -1 on failure.</summary>
        Private Function WriteWith(context As RecipeContext, source As String, method As CompressionMethod,
                                   name As String) As Long
            Dim settings As New CompressionSettings() With {.Method = method, .Level = 9}
            Dim archivePath = context.PathTo(name & settings.RecommendedFileExtension)
            Dim started = ArchiveWriter.Create(archivePath, settings)
            If Not started.Succeeded Then
                context.Say(started.ToString())
                Return -1
            End If
            Using writer = started.Writer
                Dim added = writer.AddDirectory(source, Nothing, Nothing)
                If Not added.Succeeded Then
                    context.Say(added.ToString())
                    Return -1
                End If
                Dim finished = writer.Complete()
                If Not finished.Succeeded Then
                    context.Say(finished.ToString())
                    Return -1
                End If
            End Using
            Return New FileInfo(archivePath).Length
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;
using System.Text;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Write the same files with bzip2, LZMA and XZ, and see what each one costs.
    /// </summary>
    /// <remarks>
    /// Deflate is what every ZIP reader implements and what this library writes unless told otherwise. The
    /// later methods — bzip2 (12), LZMA (14) and XZ (95) — compress better, sometimes much better, at the price
    /// of a reader that has to implement them. A store-and-Deflate reader will open such an archive, list its
    /// entries and then fail to extract them, which is a worse experience than being refused outright.
    /// That is what WinZip's <c>.zipx</c> extension is for, and
    /// <see cref="CompressionSettings.RecommendedFileExtension"/> says which name a given set of settings calls
    /// for. The extension changes nothing inside the archive: the bytes are a ZIP either way and each entry's
    /// header carries its method as always. The writer also reports the choice as an interoperability warning,
    /// so a caller who did not think about it finds out anyway.
    /// Which to pick depends on the data, and this recipe prints the evidence rather than asserting a ranking.
    /// On the documentation-like prose it generates, bzip2 wins comfortably — a block sort suits text with
    /// little long-range structure, and the reference bzip2 and LZMA rank the same way round on these bytes —
    /// while LZMA and XZ come in a little under Deflate. On a source tree or a log file the order is usually
    /// the other way about, which is the point: measure your own data.
    /// One thing worth knowing about the levels. From five up the encoder chooses what to emit by **price**,
    /// pricing every candidate through the range coder and taking the cheapest path; below five it takes the
    /// longest match it can find, which is about six times faster and, on prose, some forty per cent worse.
    /// 7-Zip draws the line in the same place.
    /// </remarks>
    internal static class ZipxMethodsRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var source = context.CreateSampleTree();
            // A quarter of a mebibyte of prose, because on a handful of small files the per-entry overhead of
            // the later methods swamps what they save and the comparison says nothing. This is the size at
            // which the choice starts to matter.
            File.WriteAllBytes(Path.Combine(source, "manual.txt"), Prose(256 * 1024));
            var expected = File.ReadAllBytes(Path.Combine(source, "manual.txt"));

            // Deflate first, as the baseline every reader can manage.
            var baseline = WriteWith(context, source, CompressionMethod.Deflate, "baseline");
            if (baseline < 0)
            {
                return RecipeOutcome.Failed;
            }

            context.Say("Deflate: {0:N0} bytes, recommended name .zip", baseline);

            foreach (var method in new[] { CompressionMethod.BZip2, CompressionMethod.Lzma, CompressionMethod.Xz })
            {
                var settings = new CompressionSettings { Method = method, Level = 9 };
                // The name the convention calls for, which is advice rather than something done behind the
                // caller's back: this recipe uses it to name the file.
                var extension = settings.RecommendedFileExtension;
                if (extension != ".zipx")
                {
                    context.Say("{0} should recommend .zipx, not {1}", method, extension);
                    return RecipeOutcome.Failed;
                }

                var archivePath = context.PathTo(method.ToString().ToLowerInvariant() + extension);
                var started = ArchiveWriter.Create(archivePath, settings);
                if (!started.Succeeded)
                {
                    context.Say(started.ToString());
                    return RecipeOutcome.Failed;
                }

                var warned = false;
                using (var writer = started.Writer)
                {
                    var added = writer.AddDirectory(source, null, null);
                    if (!added.Succeeded)
                    {
                        context.Say(added.ToString());
                        return RecipeOutcome.Failed;
                    }

                    var finished = writer.Complete();
                    if (!finished.Succeeded)
                    {
                        context.Say(finished.ToString());
                        return RecipeOutcome.Failed;
                    }

                    foreach (var warning in writer.InteropWarnings)
                    {
                        if (warning.Feature.IndexOf(".zipx", StringComparison.Ordinal) >= 0)
                        {
                            warned = true;
                        }
                    }
                }

                if (!warned)
                {
                    context.Say("{0} should have reported the naming convention as an interoperability warning", method);
                    return RecipeOutcome.Failed;
                }

                // And it has to read back, which is the only claim that matters.
                var opened = Archive.Open(archivePath);
                if (!opened.Succeeded)
                {
                    context.Say(opened.ToString());
                    return RecipeOutcome.Failed;
                }

                using (var archive = opened.Archive)
                {
                    var target = context.PathTo("out-" + method);
                    var extracted = archive.ExtractAll(target);
                    if (!extracted.Succeeded)
                    {
                        context.Say(extracted.ToString());
                        return RecipeOutcome.Failed;
                    }

                    var recovered = File.ReadAllBytes(Path.Combine(target, "manual.txt"));
                    if (!RecipeContext.SameBytes(expected, recovered))
                    {
                        context.Say("{0} did not give back what it was given", method);
                        return RecipeOutcome.Failed;
                    }
                }

                var size = new FileInfo(archivePath).Length;
                context.Say("{0}: {1:N0} bytes ({2:P0} of Deflate), read back byte for byte, named {3}",
                            method, size, size / (double)baseline, Path.GetFileName(archivePath));
            }

            return RecipeOutcome.Passed;
        }

        /// <summary>
        /// Sentences drawn from a small vocabulary: text that compresses the way documentation does rather than
        /// the way a single repeated byte does.
        /// </summary>
        private static byte[] Prose(int length)
        {
            var words = new[]
            {
                "archive", "entry", "method", "deflate", "dictionary", "window", "match", "literal", "checksum",
                "header", "volume", "stream", "reader", "writer", "compressed", "uncompressed", "the", "a",
                "and", "of", "that", "which"
            };
            var random = new Random(20260911);
            var builder = new StringBuilder(length + 64);
            while (builder.Length < length)
            {
                var wordsInSentence = 6 + random.Next(12);
                for (var index = 0; index < wordsInSentence; index++)
                {
                    if (index > 0)
                    {
                        builder.Append(' ');
                    }

                    builder.Append(words[random.Next(words.Length)]);
                }

                builder.Append(". ");
                if (random.Next(6) == 0)
                {
                    builder.Append(Environment.NewLine);
                }
            }

            return Encoding.UTF8.GetBytes(builder.ToString().Substring(0, length));
        }

        /// <summary>Writes the tree with one method and returns the archive's size, or -1 on failure.</summary>
        private static long WriteWith(RecipeContext context, string source, CompressionMethod method, string name)
        {
            var settings = new CompressionSettings { Method = method, Level = 9 };
            var archivePath = context.PathTo(name + settings.RecommendedFileExtension);
            var started = ArchiveWriter.Create(archivePath, settings);
            if (!started.Succeeded)
            {
                context.Say(started.ToString());
                return -1;
            }

            using (var writer = started.Writer)
            {
                var added = writer.AddDirectory(source, null, null);
                if (!added.Succeeded)
                {
                    context.Say(added.ToString());
                    return -1;
                }

                var finished = writer.Complete();
                if (!finished.Succeeded)
                {
                    context.Say(finished.ToString());
                    return -1;
                }
            }

            return new FileInfo(archivePath).Length;
        }
    }
}

VB.NET

Option Strict On
Option Explicit On
Option Infer On

Imports System
Imports System.IO
Imports System.Text
Imports Bastion.Archive
Imports Bastion.Archive.Codecs

Namespace Bastion.Archive.Samples.Cookbook

    ''' <summary>
    ''' Compress and decompress Zstandard, including the frames a reader is expected to walk past.
    ''' </summary>
    ''' <remarks>
    ''' Zstandard is one class each way and no ceremony, so what this recipe is really about is the three
    ''' things about the format that surprise people.
    ''' <para>
    ''' A <c>.zst</c> file is **frames concatenated**, exactly as gzip is members concatenated, and one kind of
    ''' frame is not content at all: a **skippable frame** carries whatever an application wants to put beside
    ''' the data, and a decoder is required to step over it without comment. Tools use them for their own
    ''' metadata, so a reader that choked on one would fail on files that are perfectly sound.
    ''' </para>
    ''' <para>
    ''' A frame's header names the window it needs, and a file is free to ask for far more than the machine
    ''' has; the decoder therefore takes a cap and refuses anything above it rather than trying
    ''' and falling over.
    ''' </para>
    ''' <para>
    ''' And the frame ends with a checksum of what it produced, which is the XXH64 of the content cut down to
    ''' four bytes. It is optional, and writing it is the sensible default.
    ''' </para>
    ''' </remarks>
    Friend Module ZstdDecodeRecipe

        ''' <summary>Runs the recipe.</summary>
        Public Function Run(context As RecipeContext) As RecipeOutcome
            Dim content = Encoding.UTF8.GetBytes(
                GZipStreamUsageRecipe.Repeat("the quick brown fox jumps over the lazy dog. ", 2000))

            Dim singlePath = context.PathTo("payload.zst")
            Dim blocks As Integer
            Using file As New FileStream(singlePath, FileMode.Create, FileAccess.Write)
                Dim writer As New ZstdEncoderStream(file, 5, True, leaveOpen:=True)
                Try
                    writer.Write(content, 0, content.Length)
                Finally
                    writer.Dispose()
                End Try
                blocks = writer.BlockCount
            End Using
            context.Say("{0} in, {1} out in {2} block(s), window {3}",
                        RecipeContext.Readable(content.Length),
                        RecipeContext.Readable(New FileInfo(singlePath).Length), blocks,
                        RecipeContext.Readable(1024 * 1024))

            Using file As New FileStream(singlePath, FileMode.Open, FileAccess.Read)
                Using reader As New ZstdDecoderStream(file, leaveOpen:=True)
                    Using produced As New MemoryStream()
                        GZipStreamUsageRecipe.CopyAll(reader, produced)
                        If Not RecipeContext.SameBytes(content, produced.ToArray()) Then
                            context.Say("the bytes that came back are not the bytes that went in")
                            Return RecipeOutcome.Failed
                        End If
                        context.Say("read back {0} from {1} frame(s) of {2} block(s), window {3}",
                                    RecipeContext.Readable(produced.Length), reader.FrameCount,
                                    reader.BlockCount, RecipeContext.Readable(reader.WindowBytes))
                    End Using
                End Using
            End Using

            ' Two content frames with a skippable one between them, which a reader must step over in silence.
            Dim joinedPath = context.PathTo("joined.zst")
            Dim first = Encoding.UTF8.GetBytes("the first frame" & Environment.NewLine)
            Dim second = Encoding.UTF8.GetBytes("the second frame" & Environment.NewLine)
            Using file As New FileStream(joinedPath, FileMode.Create, FileAccess.Write)
                WriteFrame(file, first)
                Dim aside = SkippableFrame(Encoding.ASCII.GetBytes("metadata some other tool left here"))
                file.Write(aside, 0, aside.Length)
                WriteFrame(file, second)
            End Using

            Using file As New FileStream(joinedPath, FileMode.Open, FileAccess.Read)
                Using reader As New ZstdDecoderStream(file, leaveOpen:=True)
                    Using produced As New MemoryStream()
                        GZipStreamUsageRecipe.CopyAll(reader, produced)
                        Dim text = Encoding.UTF8.GetString(produced.ToArray())
                        Dim expected = Encoding.UTF8.GetString(first) & Encoding.UTF8.GetString(second)
                        If Not String.Equals(text, expected, StringComparison.Ordinal) Then
                            context.Say("the joined file read back as: " & text.Replace(Environment.NewLine, "|"))
                            Return RecipeOutcome.Failed
                        End If
                        context.Say("two frames read as one stream, with a skippable frame stepped over between them")
                    End Using
                End Using
            End Using

            ' The memory cap, refused rather than attempted.
            Using file As New FileStream(singlePath, FileMode.Open, FileAccess.Read)
                Try
                    Dim taken As Integer
                    Using reader As New ZstdDecoderStream(file, leaveOpen:=True, maximumWindowBytes:=1024)
                        Dim scratch(255) As Byte
                        taken = reader.Read(scratch, 0, scratch.Length)
                    End Using
                    context.Say("a 1 KiB window cap gave back {0} bytes from a frame that needs more, " &
                                "which it must not", taken)
                    Return RecipeOutcome.Failed
                Catch ex As ArchiveException
                    context.Say("a 1 KiB window cap refused the file: {0}", ex.ErrorCode)
                End Try
            End Using

            Return RecipeOutcome.Passed
        End Function

        ''' <summary>Writes one complete frame of content.</summary>
        Private Sub WriteFrame(destination As Stream, content As Byte())
            Using writer As New ZstdEncoderStream(destination, 5, True, leaveOpen:=True)
                writer.Write(content, 0, content.Length)
                writer.Complete()
            End Using
        End Sub

        ''' <summary>
        ''' A skippable frame: a magic number in the reserved range, a length, and whatever the application
        ''' wanted to carry. It holds no content and every decoder is required to walk past it.
        ''' </summary>
        Private Function SkippableFrame(payload As Byte()) As Byte()
            Dim frame(8 + payload.Length - 1) As Byte
            ' 0x184D2A50 through 0x184D2A5F are all skippable; the low nibble is the application's to choose.
            frame(0) = &H50
            frame(1) = &H2A
            frame(2) = &H4D
            frame(3) = &H18
            For index = 0 To 3
                frame(4 + index) = CByte((CLng(payload.Length) >> (8 * index)) And &HFFL)
            Next
            System.Buffer.BlockCopy(payload, 0, frame, 8, payload.Length)
            Return frame
        End Function

    End Module

End Namespace

C#

using System;
using System.IO;
using System.Text;
using Bastion.Archive.Codecs;

namespace Bastion.Archive.Samples.Cookbook
{
    /// <summary>
    /// Compress and decompress Zstandard, including the frames a reader is expected to walk past.
    /// </summary>
    /// <remarks>
    /// Zstandard is one class each way and no ceremony, so what this recipe is really about is the three
    /// things about the format that surprise people.
    /// <para>
    /// A <c>.zst</c> file is <b>frames concatenated</b>, exactly as gzip is members concatenated, and one kind
    /// of frame is not content at all: a <b>skippable frame</b> carries whatever an application wants to put
    /// beside the data, and a decoder is required to step over it without comment. Tools use them for their
    /// own metadata, so a reader that choked on one would fail on files that are perfectly sound.
    /// </para>
    /// <para>
    /// A frame's header names the window it needs, and a file is free to ask for far more than the machine
    /// has; the decoder therefore takes a cap and refuses anything above it rather than trying
    /// and falling over.
    /// </para>
    /// <para>
    /// And the frame ends with a checksum of what it produced, which is the XXH64 of the content cut down to
    /// four bytes. It is optional, and writing it is the sensible default.
    /// </para>
    /// </remarks>
    internal static class ZstdDecodeRecipe
    {
        /// <summary>Runs the recipe.</summary>
        public static RecipeOutcome Run(RecipeContext context)
        {
            var content = Encoding.UTF8.GetBytes(
                GZipStreamUsageRecipe.Repeat("the quick brown fox jumps over the lazy dog. ", 2000));

            var singlePath = context.PathTo("payload.zst");
            int blocks;
            using (var file = new FileStream(singlePath, FileMode.Create, FileAccess.Write))
            {
                var writer = new ZstdEncoderStream(file, 5, true, leaveOpen: true);
                try
                {
                    writer.Write(content, 0, content.Length);
                }
                finally
                {
                    writer.Dispose();
                }

                blocks = writer.BlockCount;
            }

            context.Say("{0} in, {1} out in {2} block(s), window {3}",
                RecipeContext.Readable(content.Length),
                RecipeContext.Readable(new FileInfo(singlePath).Length), blocks,
                RecipeContext.Readable(1024 * 1024));

            using (var file = new FileStream(singlePath, FileMode.Open, FileAccess.Read))
            using (var reader = new ZstdDecoderStream(file, leaveOpen: true))
            using (var produced = new MemoryStream())
            {
                GZipStreamUsageRecipe.CopyAll(reader, produced);
                if (!RecipeContext.SameBytes(content, produced.ToArray()))
                {
                    context.Say("the bytes that came back are not the bytes that went in");
                    return RecipeOutcome.Failed;
                }

                context.Say("read back {0} from {1} frame(s) of {2} block(s), window {3}",
                    RecipeContext.Readable(produced.Length), reader.FrameCount,
                    reader.BlockCount, RecipeContext.Readable(reader.WindowBytes));
            }

            // Two content frames with a skippable one between them, which a reader must step over in silence.
            var joinedPath = context.PathTo("joined.zst");
            var first = Encoding.UTF8.GetBytes("the first frame" + Environment.NewLine);
            var second = Encoding.UTF8.GetBytes("the second frame" + Environment.NewLine);
            using (var file = new FileStream(joinedPath, FileMode.Create, FileAccess.Write))
            {
                WriteFrame(file, first);
                var aside = SkippableFrame(Encoding.ASCII.GetBytes("metadata some other tool left here"));
                file.Write(aside, 0, aside.Length);
                WriteFrame(file, second);
            }

            using (var file = new FileStream(joinedPath, FileMode.Open, FileAccess.Read))
            using (var reader = new ZstdDecoderStream(file, leaveOpen: true))
            using (var produced = new MemoryStream())
            {
                GZipStreamUsageRecipe.CopyAll(reader, produced);
                var text = Encoding.UTF8.GetString(produced.ToArray());
                var expected = Encoding.UTF8.GetString(first) + Encoding.UTF8.GetString(second);
                if (!string.Equals(text, expected, StringComparison.Ordinal))
                {
                    context.Say("the joined file read back as: " + text.Replace(Environment.NewLine, "|"));
                    return RecipeOutcome.Failed;
                }

                context.Say("two frames read as one stream, with a skippable frame stepped over between them");
            }

            // The memory cap, refused rather than attempted.
            using (var file = new FileStream(singlePath, FileMode.Open, FileAccess.Read))
            {
                try
                {
                    int taken;
                    using (var reader = new ZstdDecoderStream(file, leaveOpen: true, maximumWindowBytes: 1024))
                    {
                        var scratch = new byte[256];
                        taken = reader.Read(scratch, 0, scratch.Length);
                    }

                    context.Say("a 1 KiB window cap gave back {0} bytes from a frame that needs more, " +
                                "which it must not", taken);
                    return RecipeOutcome.Failed;
                }
                catch (ArchiveException ex)
                {
                    context.Say("a 1 KiB window cap refused the file: {0}", ex.ErrorCode);
                }
            }

            return RecipeOutcome.Passed;
        }

        /// <summary>Writes one complete frame of content.</summary>
        private static void WriteFrame(Stream destination, byte[] content)
        {
            using (var writer = new ZstdEncoderStream(destination, 5, true, leaveOpen: true))
            {
                writer.Write(content, 0, content.Length);
                writer.Complete();
            }
        }

        /// <summary>
        /// A skippable frame: a magic number in the reserved range, a length, and whatever the application
        /// wanted to carry. It holds no content and every decoder is required to walk past it.
        /// </summary>
        private static byte[] SkippableFrame(byte[] payload)
        {
            var frame = new byte[8 + payload.Length];
            // 0x184D2A50 through 0x184D2A5F are all skippable; the low nibble is the application's to choose.
            frame[0] = 0x50;
            frame[1] = 0x2A;
            frame[2] = 0x4D;
            frame[3] = 0x18;
            for (var index = 0; index < 4; index++)
            {
                frame[4 + index] = (byte)((payload.Length >> (8 * index)) & 0xFF);
            }

            Buffer.BlockCopy(payload, 0, frame, 8, payload.Length);
            return frame;
        }
    }
}