ManagedCode.FileContext 1.0.0

ManagedCode.FileContext

Give your .NET agents a workspace they can explore, understand, and edit.

FileContext connects ManagedCode.Storage to Microsoft Agent Framework. Agents can discover files, search their contents, read relevant line ranges, and work across Markdown documents as a knowledge graph. Enable write tools when the agent needs to create or edit files.

Your host supplies an IStorage backend and a model client. FileContext supplies the scoped file tools.

Quick start · Agent integration · Tools · Limits · Documentation

What you get

Product code depends only on ManagedCode.Storage.Core, so concrete storage providers stay in your application. The integration suite exercises the real filesystem provider; other backends use the same IStorage contract.

flowchart LR
  Agent["Agent Framework agent"] --> Context["FileContextProvider"]
  Context --> Files["Standard file tools"]
  Context --> Ranges["Range and metadata tools"]
  Context --> Graph["Markdown graph tools"]
  Files --> Store["IStorage workspace"]
  Ranges --> Store
  Graph --> Store
  Graph --> Markdown["ManagedCode.MarkdownLd.Kb"]

Install

Requires .NET 10. Add FileContext and the storage provider your application uses:

dotnet add package ManagedCode.FileContext --version 1.0.0
dotnet add package ManagedCode.Storage.FileSystem --version 10.0.7

The examples below also use the DI service-provider implementation:

dotnet add package Microsoft.Extensions.DependencyInjection --version 10.0.11

Quick start

This example creates a local workspace, adds a Markdown document through the direct storage API, and reads just its second line. It runs without a model or API key.

using ManagedCode.FileContext;
using ManagedCode.Storage.FileSystem;
using ManagedCode.Storage.FileSystem.Options;
using Microsoft.Extensions.DependencyInjection;

using var storage = new FileSystemStorage(new FileSystemStorageOptions
{
    BaseFolder = Path.Combine(AppContext.BaseDirectory, "agent-workspace"),
    CreateContainerIfNotExists = true,
});

var created = await storage.CreateContainerAsync();
if (!created.IsSuccess)
{
    throw new IOException("Could not initialize the file workspace.");
}

var services = new ServiceCollection();
services.AddManagedCodeFileContext(storage, options =>
{
    options.RootPrefix = "project";
    options.RequireReadToolApproval = false;
});

await using var serviceProvider = services.BuildServiceProvider();
var store = serviceProvider.GetRequiredService<ManagedCodeStorageFileStore>();
await store.WriteAsync("docs/retries.md", "# Retry policy\nRetry transient errors up to three times.");

var context = serviceProvider.GetRequiredService<IFileContext>();
var page = await context.ReadRangeAsync("docs/retries.md", startLine: 2, lineCount: 1);
Console.WriteLine(page.Content);
// Retry transient errors up to three times.

The host creates the example file directly. Agent write tools remain disabled. Approval is disabled for reads in this example; the library defaults to requiring approval for both reads and writes.

Connect an agent

Given the serviceProvider above and your configured IChatClient modelClient, add the context provider and the function-invocation pipeline:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var fileTools = serviceProvider.GetRequiredService<FileContextProvider>();
using var client = modelClient.AsBuilder()
    .UseAIContextProviders(fileTools)
    .UseFunctionInvocation()
    .Build();

var agent = new ChatClientAgent(client,
    new ChatClientAgentOptions { UseProvidedChatClientAsIs = true });

var response = await agent.RunAsync(
    "Find the retry policy in docs and quote the relevant lines.");
Console.WriteLine(response.Text);

modelClient is supplied by your model-provider integration. UseFunctionInvocation() executes the tools requested by the model. Hosts keeping the default approval settings must also handle Agent Framework's approval flow.

Tool catalog

Standard file_access_* tools come from Agent Framework's FileAccessProvider. FileContext adds complementary range, metadata, and Markdown tools.

All enabled tools require approval by default. Configure write access when registering the workspace:

services.AddManagedCodeFileContext(storage, options =>
{
    options.EnableWriteTools = true;
    options.RequireWriteToolApproval = true;
});

Explicit metadata results

A missing file is a normal lookup outcome. file_context_info returns:

{"status":"not_found","path":"docs/missing.md"}

An existing file returns status: "found", its logical path, and an info object containing path, length, contentType, and lastModified.

These results are tested through tool invocation, session serialization/restoration, and the next user request. The direct C# API, IFileContext.GetInfoAsync, retains its nullable metadata contract. Storage errors and invalid paths still fail; a missing file in a range read throws FileNotFoundException.

Navigate large files

Read the needed window, then use its continuation metadata:

var page = await context.ReadRangeAsync("logs/build.log", startLine: 401, lineCount: 100);
Console.WriteLine(page.Content);

if (page.HasMore)
{
    var next = await context.ReadRangeAsync("logs/build.log", page.EndLine + 1, 100);
    Console.WriteLine(next.Content);
}

Results include StartLine, EndLine, HasMore, and TotalLines when the end is reached. Reads stream through the file and retain only bounded content; non-seekable streams are supported. Files above the full-read limit must be accessed through range reads.

Explore Markdown as a graph

Use ManagedCode.MarkdownLd.Kb to connect and search concepts across the Markdown documents in your workspace:

var matches = await context.SearchMarkdownGraphAsync("retry policy", "docs");
var graph = await context.ExportMarkdownGraphAsync(MarkdownGraphFormat.Mermaid, "docs");
Console.WriteLine(graph.Content);

Each operation builds from the current selected .md files, subject to document and size limits. Graph exports support Mermaid, DOT, Turtle, and JSON-LD. This package consumes existing Markdown; conversion from PDF, DOCX, or XLSX is outside its scope.

Work with multiple files

A model turn can contain several tool calls, each with its own path and result. Function invocation is sequential by default. Enable concurrency in your client pipeline when operations are independent:

.UseFunctionInvocation(configure: client => client.AllowConcurrentInvocation = true)

Direct API consumers can also use Task.WhenAll for independent reads:

var pages = await Task.WhenAll(
    context.ReadRangeAsync("docs/retries.md", 1, 20),
    context.ReadRangeAsync("docs/timeouts.md", 1, 20));

The tests cover multiple calls in one model turn and concurrent writes/reads on eight separate files. Your storage provider must support the chosen concurrency. Serialize dependent operations and writes to the same path: FileContext provides no cross-file transaction or same-file write lock.

Separate workspaces with keyed storage

Register keyed services before building the service provider. Each registration can have its own options and storage prefix:

using ManagedCode.Storage.Core;

var workspaceServices = new ServiceCollection();
workspaceServices.AddKeyedSingleton<IStorage>("research", researchStorage);
workspaceServices.AddKeyedManagedCodeFileContext("research", options =>
{
    options.RootPrefix = "agents/research";
});

using var workspaces = workspaceServices.BuildServiceProvider();
var tools = workspaces.GetRequiredKeyedService<FileContextProvider>("research");

Bounds and workspace isolation

Paths are logical, relative, and /-separated. RootPrefix scopes storage access. Path validation rejects traversal and unsafe path forms before storage calls. File contents remain untrusted tool data.

These settings are available through FileContextOptions; their named defaults are exposed by FileContextDefaults. Credentials, container lifecycle, authorization, and session persistence remain host responsibilities. When saving conversations, preserve tool-call/result pairs and handle interrupted turns before replaying history.

Verified with real integrations

The suite runs against real filesystem storage, real Markdown graph builds, and an in-process LlmTck HTTP service using Agent Framework's actual function-invocation pipeline. No live model or API key is required.

Coverage includes all advertised tools, empty/error results, restored sessions, concurrent file operations, Unicode buffer boundaries, and bounded range reads from a sparse 1 GiB file. CI enforces at least 95% product line coverage, formatting, static analysis, build, tests, and package validation.

dotnet restore ManagedCode.FileContext.slnx
dotnet format ManagedCode.FileContext.slnx --verify-no-changes
dotnet build ManagedCode.FileContext.slnx --configuration Release
dotnet test tests/ManagedCode.FileContext.Tests/ManagedCode.FileContext.Tests.csproj --configuration Release /p:CollectCoverage=true
dotnet pack src/ManagedCode.FileContext/ManagedCode.FileContext.csproj --configuration Release --no-build --output artifacts

Documentation

Releases and license

Version 1.0.0 is defined centrally in Directory.Build.props. NuGet publication runs only through GitHub Actions from a matching version tag, such as v1.0.0.

MIT licensed · Built by ManagedCode