WinCfApiWrapper 1.2.0

WinCfApiWrapper

Expose a read-only content source as a Windows Cloud Files sync root. Files start as placeholders and their contents are fetched on demand. Built-in containers support ZIP, TAR, TAR.GZ, GZip, Brotli, Deflate, and ZLib; implement IContentContainer for other sources.

Requirements

• Windows x64, Windows 10 version 1709 (build 16299) or later with Cloud Files support.
• .NET 8 or later, targeting net8.0-windows or a later Windows target framework.

Installation

dotnet add package WinCfApiWrapper

The example below uses the Microsoft dependency injection container. If your application does not already reference it, also install Microsoft.Extensions.DependencyInjection.

Quick start

using Microsoft.Extensions.DependencyInjection;
using WinCfApiWrapper;
using WinCfApiWrapper.Public;
using WinCfApiWrapper.Public.Containers;

var services = new ServiceCollection();
services.AddWinCfApiWrapper();
using var provider = services.BuildServiceProvider();

var factory = provider.GetRequiredService<ICloudMountFactory>();
await using ICloudMount mount = factory.Open(new CloudMountOptions
{
    Container = new ZipContainer(_ => File.OpenRead(@"C:\archives\sample.zip")),
    Root = @"C:\Cloud\Sample",
});

mount.Error += (_, error) => Console.Error.WriteLine(error.Exception);
await mount.MountAsync();
Console.WriteLine($"Mounted at {mount.Root}");
await mount.HydrateAsync(@"docs\hello.txt");

MountAsync creates or validates placeholders and connects the sync root; it does not download all files. Windows fetches contents when needed. Use HydrateAsync(path) for one file or HydrateAllAsync(progress) for all files. Bulk hydration reports progress and throws an AggregateException if any files fail. Background fetch failures are reported through Error and the configured logger.

Production trusted-build-artifact mode: use TrustedContentId, SkipResumeValidation = true and ZIP validateEntryMetadata: false together only for immutable, app-owned snapshots. These do not skip initial indexing or Windows-required path checks. See TrustedID benchmark and no-regression contract for a reproducible Windows performance harness and merge policy.

For remote ZIPs, use ZipContainer.FromHttp(httpClient, archiveUri) to fetch bounded byte ranges. A stream factory that downloads into a MemoryStream still downloads the archive on every invocation. Set CloudMountOptions.Progress to an IProgress<OperationProgress> for startup, resume, file fetch, explicit hydration, and shutdown updates. See release feedback and performance for verified behavior and trusted-source settings.

Use a dedicated, disposable mount folder containing no user data. CloudMountOptions.Root is a base path; the actual mount.Root includes a content fingerprint. Disposing the mount disconnects it. To unregister and delete the folder, call ISyncRootManager.Unregister(mount.Root) after disposal. See the lifecycle and cleanup guide before integrating cleanup into an application.

Public API

Public interfaces and built-in containers are in WinCfApiWrapper.Public and WinCfApiWrapper.Public.Containers. AddWinCfApiWrapper() is in WinCfApiWrapper. When the host registers Microsoft.Extensions.Logging, lifecycle and failure events are logged; otherwise the library uses a no-op logger.

Guides and contributing

• Documentation index
• Containers: built-in formats, stream ownership, and custom container contracts.
• Architecture and lifecycle: hydration, errors, resume, and safe cleanup.
• Development: building, testing, fuzzing, and coverage.
• Security model: trust boundaries and limitations.
• Releasing and provenance: release cadence, package verification, and recovery.
• Contributing: submitting issues, tests, and pull requests.
• Security policy: private vulnerability reporting.

Report ordinary bugs and request features through GitHub issues. Report vulnerabilities privately using the security policy.