CfSharp

CfSharp is a Windows-only .NET library for building Cloud Files sync providers with a safe, idiomatic C# API. It keeps the complete Windows Cloud Files surface reachable while taking care of native structure layout, callback lifetime, cancellation, durable coordination, and failure translation.

Preview channel: CfSharp preview packages are published from develop by the manually triggered Preview release workflow. Stable 1.0.0 is reserved for the protected main release path.

What is included

Package	Purpose
CfSharp.Native	ABI-accurate bindings for cfapi.h and CldApi.dll.
CfSharp	High-level sync-root, placeholder, hydration, provider, local-change, and remote-change APIs.
CfSharp.Storage.Sqlite	Optional transactional state store using a caller-owned SQLite database.

The dependency direction is one way: CfSharp.Native is the interop layer, CfSharp provides the safe domain API, and the SQLite package depends on CfSharp. Remote transport, authentication, content bytes, and business conflict policy remain application-owned.

Quick start

Requirements

• Windows 10 version 1709 (build 16299) or later for the core Cloud Files API;
• .NET 10 SDK selected by global.json;
• x64 or ARM64 for the current support target. x86 is outside the stable release matrix;
• a sync root directory and a durable state database located outside that sync root.

Build from source

git clone https://github.com/MirrorPulse/CfSharp.git
cd CfSharp
dotnet restore CfSharp.sln
dotnet build CfSharp.sln --configuration Release --no-restore
dotnet test CfSharp.sln --configuration Release --no-build

The first sample provider is available under samples/CfSharp.SampleProvider. It mirrors a local content directory as online-only placeholders:

dotnet run --project samples/CfSharp.SampleProvider -- `
  run C:\CloudContent `
  C:\CloudSyncRoot `
  --state-db C:\CloudState\cfsharp.db `
  --once

A small example

CfSharp makes ownership and lifecycle boundaries explicit. The SQLite path is supplied by the application and must not be placed inside the managed sync root.

ICloudStateStoreFactory stateStoreFactory = new SqliteCloudStateStoreFactory(
    @"C:\ProgramData\ExampleProvider\Accounts\account-42\cfsharp.db");

SyncRootRegistrationOptions registration =
    SyncRootRegistrationOptions.CreateBuilder("Example Cloud", "1.0.0")
        .WithProviderId(providerId)
        .WithSyncRootIdentity(accountIdentity)
        .WithRootMarkedInSync()
        .Build();

await using CloudFileSystem fileSystem = CloudFileSystem.CreateBuilder(
        @"C:\Users\Example\Example Cloud")
    .WithStateStore(stateStoreFactory)
    .WithRegistration(registration)
    .WithContentProvider(contentProvider)
    .Build();

await fileSystem.StartAsync(cancellationToken);
CloudFile report = fileSystem.GetFile(@"Documents\report.pdf");
CloudItemSnapshot snapshot = await report.InspectAsync(cancellationToken);

CloudFileSystem opens the configured store only after validating the sync root and owns it after a successful start. Disposing the facade stops process-scoped work and closes durable state, but does not unregister the persistent Windows sync-root registration. Call CloudSyncRoot.Unregister() only for explicit account removal or uninstall.

Documentation

• Documentation home
• Getting started
• Architecture and ownership
• Sync-root lifecycle
• Placeholders and hydration
• Local change feed
• Remote change application
• SQLite state
• Platform support
• Troubleshooting

The generated API reference is published with the documentation site at https://mirrorpulse.github.io/cfsharp/.

Release automation, NuGet trusted publishing, version calculation, and branch rules are described in the release and branch model.

Development notes

The repository is Windows-first and keeps unsafe interop isolated in CfSharp.Native. Public APIs document ownership, lifetime, thread-safety, platform requirements, failure modes, and relevant native behavior. Changes should follow the atomic-commit and verification rules in CONTRIBUTING.md.

dotnet format CfSharp.sln --verify-no-changes --no-restore
dotnet build CfSharp.sln --configuration Release --no-restore
dotnet test CfSharp.sln --configuration Release --no-build
pwsh ./eng/verify-platform-matrix.ps1
pwsh ./eng/verify-runtime-boundaries.ps1 -Configuration Release

License

CfSharp is licensed under the Apache License 2.0. Copyright © MirrorPulse Team.