CanDoItAll.FileTools.Abstractions 0.1.15

CanDoItAll.FileTools

Storage-neutral .NET and Blazor building blocks for browsing, viewing, and editing file-like resources. The repository targets .NET 10 and keeps application storage drivers, authorization, application-triggered navigation, downloads, clipboard access, and persistence in the host. Browser-native viewer behavior, notably embedded PDF actions, remains browser-owned and is documented as an explicit boundary.

Ownership

This repository owns the FileBrowser and FileInteraction contracts, runtime coordination, Blazor components, optional filesystem and Markdown adapters, and the host-side desktop launching boundary.

It does not own application authorization, persistence, remote storage integrations, browser behavior, or application deployment. Hosts retain those responsibilities. CanDoItAll.Components continues to own unrelated general-purpose components.

Choose packages

Install only the right-hand packages needed by the host. In particular, a browser-only application does not acquire Markdig or interaction renderers, and a custom provider can depend on Abstractions without taking Blazor.

Requirements

• .NET SDK 10.0.301, pinned by global.json with latest-patch roll-forward
• Windows PowerShell 5.1 or PowerShell 7 for packaging and package validation

Build and test

Run from the repository root:

dotnet restore .\CanDoItAll.FileTools.slnx --configfile .\NuGet.config
dotnet build .\CanDoItAll.FileTools.slnx --configuration Release --no-restore
dotnet test .\CanDoItAll.FileTools.slnx --configuration Release --no-build

Run the maintained Sandbox:

dotnet run --project .\samples\CanDoItAll.FileTools.Sandbox\CanDoItAll.FileTools.Sandbox.csproj --configuration Release --no-build --no-restore

Minimal FileBrowser

Create a provider and session in the host's scope, then dispose the session with that scope:

using CanDoItAll.FileTools.FileBrowser;
using CanDoItAll.FileTools.Providers.FileSystem;

var provider = new FileSystemFileBrowserProvider(
    new FileSystemFileBrowserOptions(
        new FileBrowserSourceId("workspace"),
        configuredRootPath,
        displayName: "Workspace"));

IFileBrowserSession session = new FileBrowserSession(
    [provider],
    new FileBrowserSessionOptions(
        pageSize: 50,
        retentionMode: FileBrowserStateRetentionMode.Disabled));

Render the session in Razor. Files and non-navigable items notify the host; folders navigate inside the session:

@using CanDoItAll.FileTools.FileBrowser.Components

<FileBrowser Session="@session"
             DisplayMode="FileBrowserDisplayMode.Compact"
             ItemInvoked="OpenAuthorizedFileAsync"
             ActionRequested="HandleAuthorizedActionAsync" />

ItemInvoked and ActionRequested are notifications, not authorization. Re-resolve and authorize the item in the host immediately before any open, download, copy, navigation, or storage action. The component does not execute provider URIs or platform effects.

Minimal FileInteraction

Compose only the renderers the application needs. Markdown is opt-in:

using CanDoItAll.FileTools.FileInteraction.Components;
using CanDoItAll.FileTools.FileInteraction.Markdown;

builder.Services.AddFileInteractionComponents(components =>
    components
        .AddBuiltIns()
        .AddMarkdown());

Pass an opaque, host-authorized reference and a content source to the shell:

@using CanDoItAll.FileTools.FileInteraction.Components
@inject FileInteractionComponentComposition InteractionComposition

<FileInteraction Request="@request"
                 ContentSource="@contentSource"
                 Composition="@InteractionComposition"
                 SaveRequested="PersistAsync"
                 StateChanged="ObserveState" />

The host must await persistence in SaveRequested, enforce the expected content revision, and call SetPersistedRevision when a new revision is available. An exception, including FileSaveConflictException, leaves the editor dirty. StateChanged supplies the dirty/saving/conflict state needed by close guards and surrounding window chrome.

Retention and caching boundary

FileBrowser session retention is a bounded UI-navigation optimization, not an application storage cache. Use Disabled for live folders such as agent/process output. Use Bounded only when revisiting loaded pages is desirable, and call the session invalidation or refresh APIs when freshness changes. Expensive aggregate, project, remote, or content-addressed caching belongs in a host adapter outside FileTools; authorization must still be re-applied on every effect.

The included filesystem provider also implements IFileContentSource, so an authorized host can reuse it for read-only FileInteraction content without involving the browser session. The host still mints the FileReference; a browser item key is not authority, and the provider intentionally supplies no write target or optimistic-concurrency revision for mutable local files.

Ownership and migration

FileBrowser ownership moved from CanDoItAll.Components to this standalone repository. The migration is a breaking package and namespace change:

The new browser RCL does not depend on Components.BaseLib. Do not load the former global FileBrowser stylesheet or old _content/CanDoItAll.Components.FileBrowser.BaseLib/... paths; the new RCL uses isolated/collocated assets. CanDoItAll.Components continues to own simple general-purpose wrappers such as Mermaid, which hosts may register through the FileInteraction renderer seam.

Packaging

Build all eight NuGet and symbol packages through the repository adapter, then inspect their dependency, metadata, readme, symbols, static assets, and hashes:

.\tools\deployment\nugets\Build-NuGets.ps1 -Configuration Release
.\tools\validation\Test-NuGetPackages.ps1

The tools write ignored local artifacts and never publish packages. See the build and packaging guide for -NoRestore, -NoBuild, version overrides, and CI usage.

Documentation

• Package architecture and dependency direction
• FileBrowser and provider guide
• FileInteraction extension guide
• Native file-launching boundary
• Host integration and security
• Build, test, pack, and validate

The Sandbox under samples/CanDoItAll.FileTools.Sandbox demonstrates composed UI scenarios. The separate integration architecture bundle is prepared for future CanDoItAll work; none of that future host-module wiring is claimed as shipped by these packages.

License and contributions

The repository is licensed under the MIT-derived license with CanDoItAll website-link requirement. Redistributions in source or binary form must include at least one link to aicandoitall.com. One such link satisfies the added condition for a distribution containing multiple covered CanDoItAll libraries; retain each applicable copyright and permission notice.

Code contributions are limited to partners approved by the maintainer. See the contribution policy and contact the fyziktom account on LinkedIn before opening a pull request. Security reports must follow the security policy.