Onboarding: files-community/Files

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit today
• 5 active contributors
• MIT licensed
• CI configured
• ⚠ Small team — 5 top contributors
• ⚠ Concentrated ownership — top contributor handles 74% of commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

Files is a WinUI 3 / C# file manager for Windows 11 that replaces or supplements Windows Explorer. It provides multi-tab browsing, file tagging, column/grid/list views, cloud storage integration (OneDrive, Google Drive), and a dual-pane layout via its BladeView component. The app is packaged as an MSIX/MSIX bundle for the Microsoft Store and distributed via sideload appinstaller files. The solution (Files.slnx) is structured as multiple projects: src/Files.App is the main WinUI 3 app, src/Files.App.Controls holds reusable custom controls (AdaptiveGridView, BladeView), and src/Files.App.BackgroundTasks handles background WinRT tasks like update checks. Shared build config lives in Directory.Build.props and Directory.Packages.props.

Who it's for

Windows power users who want a modern file manager with multi-tab support and file tagging, and C#/WinUI 3 developers who want to contribute to or learn from a large, production-grade WinUI 3 application with real-world MVVM patterns and custom controls.

Maturity & risk

This is a mature, actively maintained open-source project with thousands of GitHub stars and years of commit history. CI is enforced via GitHub Actions (ci.yml), XAML formatting is automated (format-xaml.yml), and there are multiple CD pipelines for both stable and preview releases to the Microsoft Store and sideload. The presence of Crowdin localization, a dependabot config, and a structured issue template system all indicate production-ready project hygiene.

The project relies heavily on WinUI 3 / Windows App SDK, which still has rough edges and breaking changes between versions tracked in Directory.Packages.props. The codebase is almost entirely C# (~97%) with some C++ (~3%), making Windows-specific WinRT interop a non-trivial maintenance surface. Community-driven maintainership means response time on issues can vary, but the multi-maintainer structure and active GitHub org reduce single-maintainer risk.

Active areas of work

Active work includes CD pipeline management for both sideload-preview and store-preview channels (cd-sideload-preview.yml, cd-store-preview.yml), XAML formatting automation, and ongoing Crowdin localization updates. The presence of Configure-AppxManifest.ps1 and Create-MsixBundle.ps1 scripts suggests active packaging/release engineering work.

Get running

git clone https://github.com/files-community/Files.git cd Files

Open Files.slnx in Visual Studio 2022 (17.8+) with the Windows App SDK workload installed

Set src/Files.App as the startup project

Press F5 to build and run (requires Windows 11 or Windows 10 21H2+)

See https://files.community/docs/contributing/building-from-source for full prerequisites

Daily commands: Open Files.slnx in Visual Studio 2022, ensure 'Windows App SDK' and 'Universal Windows Platform development' workloads are installed, select the Files.App project, choose x64 Debug configuration, and press F5. No separate dev server — it deploys as a packaged MSIX app directly to the local machine.

Map of the codebase

• src/Files.App.Controls/Sidebar/SidebarView.xaml.cs — Core sidebar view code-behind that wires up the primary navigation UI, making it the entry point for understanding how folder navigation and sidebar interactions are handled.
• src/Files.App.Controls/Omnibar/Omnibar.cs — Central address/search bar control that drives path navigation and search, a fundamental user interaction surface every contributor must understand.
• src/Files.App.Controls/BreadcrumbBar/BreadcrumbBar.cs — Implements the breadcrumb navigation control that shows the current directory path and allows hierarchical navigation, critical to understanding path traversal UX.
• src/Files.App.Controls/BladeView/BladeView.cs — Core multi-pane blade layout system that enables side-by-side folder viewing, foundational to the multi-panel architecture of the file manager.
• src/Files.App.Controls/AdaptiveGridView/AdaptiveGridView.cs — The adaptive grid control used to display files and folders in grid layout, central to the primary file listing UI experience.
• Directory.Build.props — MSBuild properties applied to all projects in the solution, defining shared compilation settings, TFMs, and package versions that affect every build.
• src/Files.App.Controls/Sidebar/ISidebarViewModel.cs — Defines the ViewModel contract for the sidebar, establishing the abstraction boundary between UI and business logic that all sidebar contributors must respect.

How to make changes

Add a new custom control

1. Create a new folder under src/Files.App.Controls/ named after your control (e.g., MyControl/) and add a MyControl.cs class inheriting from the appropriate WinUI base class (Control, ContentControl, etc.). (src/Files.App.Controls/SamplePanel/SamplePanel.cs)
2. Add a MyControl.Properties.cs partial class to define all DependencyProperty registrations following the pattern used in existing controls. (src/Files.App.Controls/SamplePanel/SamplePanel.Properties.cs)
3. Add a MyControl.xaml ResourceDictionary file containing the default ControlTemplate under the correct ThemeResource keys, following the SamplePanel pattern. (src/Files.App.Controls/SamplePanel/SamplePanel.xaml)
4. Register the new control's default style in the GlobalHelper.cs or ensure it is merged into the app's ResourceDictionary so the template is discoverable at runtime. (src/Files.App.Controls/GlobalHelper.cs)

Add a new sidebar navigation item type

1. Define a new model class implementing ISidebarItemModel to provide the data contract (path, icon, display name) for the new item type. (src/Files.App.Controls/Sidebar/ISidebarItemModel.cs)
2. Extend ISidebarViewModel or its concrete implementation to expose a collection of the new item type and handle selection/invocation. (src/Files.App.Controls/Sidebar/ISidebarViewModel.cs)
3. Update SidebarView.xaml to add a DataTemplate for the new item type and bind it to the appropriate ItemTemplateSelector. (src/Files.App.Controls/Sidebar/SidebarView.xaml)
4. Update SidebarView.xaml.cs to handle any new pointer/keyboard interaction events specific to the new item type. (src/Files.App.Controls/Sidebar/SidebarView.xaml.cs)

Add a new omnibar mode (e.g., a command palette mode)

1. Create a new OmnibarMode instance or subclass in the Omnibar folder, defining its ContentTemplate and TextMemberPath via OmnibarMode.Properties.cs conventions. (src/Files.App.Controls/Omnibar/OmnibarMode.cs)
2. Add any new routed events or event args needed for mode-specific interactions in OmnibarMode.Events.cs. (src/Files.App.Controls/Omnibar/OmnibarMode.Events.cs)
3. Register the mode in Omnibar.Properties.cs by adding it to the Modes collection dependency property default or exposing a dedicated property. (src/Files.App.Controls/Omnibar/Omnibar.Properties.cs)
4. Handle mode activation/deactivation logic and text change routing in Omnibar.Events.cs, ensuring the correct OmnibarTextChangeReason is raised. (src/Files.App.Controls/Omnibar/Omnibar.Events.cs)

Add a new background task

1. Create a new class in src/Files.App.BackgroundTasks/ implementing IBackgroundTask, following the UpdateTask.cs pattern for deferral and cancellation handling. (src/Files.App.BackgroundTasks/UpdateTask.cs)
2. Register the new background task class in the Files.App.BackgroundTasks.csproj by ensuring it is included in the correct entry point declarations. (src/Files.App.BackgroundTasks/Files.App.BackgroundTasks.csproj)

Why these technologies

• WinUI 3 (Windows App SDK) — Provides modern, native Windows UI controls and Fluent Design with full access to Win32 APIs, enabling a premium Windows-native experience without UWP sandbox limitations.
• C# with XAML — Industry-standard combination for Windows desktop development; XAML enables declarative UI with data binding while C# provides strong typing and async/await for responsive I/O.
• MVVM pattern — Decouples UI (XAML views) from business logic (ViewModels), enabling testability, maintainability, and clear separation of concerns across a large contributor base.
• Central Package Management (Directory.Packages.props) — Ensures all projects in the solution use consistent NuGet package versions, preventing version conflicts and simplifying dependency upgrades across multiple projects.
• undefined — undefined

Traps & gotchas

You must have the Windows App SDK Visual Studio workload and Windows 11 SDK installed — the project will not build on macOS/Linux or in standard CI without a Windows runner. The MSIX packaging requires a code-signing certificate; the Generate-SelfCertPfx.ps1 script creates a self-signed cert for local dev but Store submissions require a real cert. Different app IDs are used for stable vs preview (configured via Configure-AppxManifest.ps1), so running both simultaneously requires separate package family names. XAML formatting is enforced by XamlStyler (Settings.XamlStyler config) — unformatted XAML will fail CI.

Architecture

Concepts to learn

• MSIX Packaging — All deployment in this repo is via MSIX bundles and appinstaller files; understanding MSIX identity, capabilities, and signing is required to build and distribute the app.
• WinUI 3 / Windows App SDK — The entire UI layer is WinUI 3 — custom controls in Files.App.Controls inherit from WinUI base classes, and the app lifecycle follows Windows App SDK patterns not classic WPF/UWP.
• WinRT Background Tasks — Files.App.BackgroundTasks/UpdateTask.cs runs as a WinRT out-of-process background task, a Windows-specific execution model with strict lifetime and trigger constraints.
• Blade/Multi-Pane UI Pattern — The BladeView control (src/Files.App.Controls/BladeView/) implements a horizontal multi-pane navigation model distinct from tabs — understanding this pattern explains how dual-pane file browsing is architected.
• AdaptiveGridView / Variable-Sized Grid Layout — AdaptiveGridView.cs implements a responsive grid that recalculates item sizes based on container width — a non-trivial custom panel layout needed for the thumbnail file view.
• Centralized NuGet Version Management (Directory.Packages.props) — The repo uses MSBuild's central package management feature to pin all NuGet versions in one file — adding or updating a dependency requires editing Directory.Packages.props, not individual .csproj files.
• XamlStyler Formatting Enforcement — XAML files are auto-formatted via XamlStyler with project-specific rules in Settings.XamlStyler; PRs with unformatted XAML fail the format-xaml.yml CI check, which surprises contributors unfamiliar with this tooling.

Related repos

• microsoft/terminal — Windows Terminal is a comparable modern WinUI/WinUI 3 shell app from Microsoft; architectural patterns for packaged Win32/WinRT apps overlap significantly.
• microsoft/WindowsAppSDK — Files is built directly on the Windows App SDK (WinUI 3); understanding SDK releases and breaking changes is essential for maintaining this app.
• microsoft/WinUI-Gallery — Official WinUI 3 control sample gallery — the primary reference for WinUI 3 control usage patterns seen throughout Files.App.Controls.
• xupefei/Locale-Emulator — Alternative Windows shell extension project — useful as a contrast for understanding MSIX packaging and Windows shell integration approaches.
• quicklook/QuickLook — Another open-source Windows file manager utility with WPF/WinRT integration, useful as a predecessor/comparison for Windows file UI patterns.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Split BreadcrumbBar.cs into focused partial classes (Events, Logic, Helpers)

The BreadcrumbBar control already has Properties split into BreadcrumbBar.Properties.cs and events into BreadcrumbBarItem.Events.cs, but BreadcrumbBar.cs itself likely contains mixed concerns (layout logic, event handling, rendering). Following the same pattern already established by BladeView (BladeView.cs + BladeView.Events.cs + BladeView.Properties.cs) and BreadcrumbBarItem (BreadcrumbBarItem.Events.cs + BreadcrumbBarItem.Properties.cs), splitting BreadcrumbBar.cs into partial classes improves readability and makes it easier for new contributors to navigate. This is a low-risk, high-value refactor aligned with the existing code conventions.

• [ ] Open src/Files.App.Controls/BreadcrumbBar/BreadcrumbBar.cs and identify distinct concern blocks: event handlers, layout/measure logic, and helper methods
• [ ] Create src/Files.App.Controls/BreadcrumbBar/BreadcrumbBar.Events.cs and move all event subscription and handler methods there, mirroring the pattern in BladeView/BladeView.Events.cs
• [ ] Ensure BreadcrumbBar.cs retains only the core control lifecycle (constructor, OnApplyTemplate, etc.) as the primary partial class
• [ ] Verify EventArgs.cs (src/Files.App.Controls/BreadcrumbBar/EventArgs.cs) is properly referenced and not duplicating anything now in the Events partial
• [ ] Build the solution and confirm no regressions in BreadcrumbBarLayout.cs or BreadcrumbBarItemAutomationPeer.cs which depend on BreadcrumbBar internals

Add unit tests project for Files.App.Controls custom controls (BladeView, BreadcrumbBar, GridSplitter)

The repository has a CI workflow at .github/workflows/ci.yml and a test result conversion script at .github/scripts/Convert-TrxToMarkdown.ps1, which strongly implies a test infrastructure exists or is expected. However, there is no visible test project for the custom controls in src/Files.App.Controls. The BladeView, BreadcrumbBar, and GridSplitter controls have non-trivial logic (BreadcrumbBarLayout.cs, AdaptiveGridView.cs, GridSplitter.Data.cs) that is completely untested. Adding a dedicated test project with unit tests for these would prevent regressions and lower the barrier for contributors to safely modify control logic.

• [ ] Create a new project src/Files.App.Controls.Tests/Files.App.Controls.Tests.csproj targeting the same framework as Files.App.Controls, referencing MSTest or xUnit
• [ ] Add it to Files.slnx so it is picked up by the CI workflow at .github/workflows/ci.yml
• [ ] Write unit tests for BreadcrumbBarLayout.cs covering item arrangement, overflow behavior, and ellipsis insertion logic
• [ ] Write unit tests for AdaptiveGridView.cs (src/Files.App.Controls/AdaptiveGridView/AdaptiveGridView.cs) covering the AdaptiveHeightValueConverter and column calculation logic in AdaptiveGridView.Properties.cs
• [ ] Write unit tests for GridSplitter data/state logic in src/Files.App.Controls/GridSplitter/GridSplitter.Data.cs (min/max constraints, drag delta clamping)
• [ ] Confirm the Convert-TrxToMarkdown.ps1 script in .github/scripts can parse the new test output and update ci.yml if needed to run the new test project

Add a XAML linting/formatting check step to the CI workflow using the existing format-xaml workflow

The repository already has a dedicated .github/workflows/format-xaml.yml workflow and a Settings.XamlStyler config file at the root, meaning XAML formatting via XamlStyler is a first

Good first issues

1. Add XML doc comments to public members in src/Files.App.Controls/AdaptiveGridView/AdaptiveGridView.Properties.cs, which currently has no inline documentation. 2. Write unit tests for AdaptiveHeightValueConverter.cs in Files.App.Controls — the converter logic is self-contained and currently appears untested. 3. Add a CONTRIBUTING.md section or wiki entry specifically documenting the Configure-AppxManifest.ps1 parameters, as new contributors setting up sideload builds have no inline guidance on the script's flags.

Top contributors

• @yair100 — 67 commits
• @dependabot[bot] — 12 commits
• @workbysaran — 6 commits
• @Lamparter — 3 commits
• @0x5bfa — 2 commits

Recent commits

• fbe494d — Build: v4.0.48 (yair100)
• ee51805 — Fix: Fixed home page freeze caused by active tags widget (#18409) (workbysaran)
• 1e56877 — Build: v4.0.47 (yair100)
• b4e1e85 — Build: v4.0.46 (yair100)
• 9a2a3e8 — Code Quality: Show indeterminate progress when update unknown (yair100)
• b1a515a — Build: v4.0.45 (yair100)
• b7e6267 — Code Quality: Dispose system tray icon during teardown (yair100)
• f9ade1a — Build: v4.0.44 (yair100)
• 272c491 — Code Quality: Modified update services to use appinstaller instead of bundle (yair100)
• 2968da7 — Code Quality: Continued working on Shelf Pane (#17308) (d2dyno1)

Security observations

• Medium · Self-Signed Certificate Generation Script — .github/scripts/Generate-SelfCertPfx.ps1. The script Generate-SelfCertPfx.ps1 generates self-signed certificates for code signing. Self-signed certificates do not provide trust chain validation and can be misused or accidentally committed with private key material. If the PFX file or its password is hardcoded or stored insecurely in CI/CD workflows, it could lead to signing key compromise. Fix: Ensure the generated PFX and its password are stored only in GitHub Encrypted Secrets, never hardcoded in scripts or committed to the repository. Use a proper CA-signed certificate for production builds. Audit the CI/CD workflow files to confirm secrets are handled securely.
• Medium · Potential Secret Exposure in CI/CD Workflow Files — .github/workflows/. Multiple CD workflow files (cd-sideload-preview.yml, cd-sideload-stable.yml, cd-store-preview.yml, cd-store-stable.yml) are present. These files orchestrate deployments and may reference signing keys, store credentials, or API tokens. Misconfigured workflow files can inadvertently expose secrets through log output, environment variable leakage, or pull-request-triggered workflows that allow untrusted code to access secrets. Fix: Review all workflow files to ensure secrets are only passed to trusted, controlled steps. Use 'pull_request_target' carefully and restrict secret access to protected branches only. Enable GitHub's secret scanning and push protection. Avoid printing environment variables or secrets to logs.
• Medium · AppxManifest Configuration Script May Expose Sensitive Build Parameters — .github/scripts/Configure-AppxManifest.ps1. The Configure-AppxManifest.ps1 script likely modifies application manifests during CI/CD. If package identity names, publisher IDs, or other sensitive parameters are passed as unmasked arguments in workflow logs, they could be exposed in build output. Fix: Ensure that any sensitive parameters (publisher certificates, store credentials) passed to this script are sourced from GitHub Encrypted Secrets and that workflow steps using these scripts have 'set -x' or equivalent debug logging disabled to prevent secret leakage in logs.
• Low · Dependency Version Pinning Risk — Directory.Packages.props, nuget.config. The presence of Directory.Packages.props and nuget.config suggests centralized NuGet package management. Without strict version pinning and hash verification, supply chain attacks (dependency confusion or package substitution) are possible. NuGet packages from public feeds could be substituted with malicious versions if internal package names overlap with public feed names. Fix: Pin all NuGet dependencies to exact versions. Consider using NuGet lock files (packages.lock.json) with the RestorePackagesWithLockFile property enabled. Configure nuget.config to use a trusted, private feed where possible, or enable package source mapping to control which packages come from which feed.
• Low · Background Task Update Mechanism Integrity — src/Files.App.BackgroundTasks/UpdateTask.cs. The UpdateTask.cs in Files.App.BackgroundTasks implements a background update task. If the update mechanism fetches binaries or manifests from remote URLs without verifying cryptographic signatures or certificate pinning, it could be vulnerable to man-in-the-middle attacks or update package tampering. Fix: Ensure all update-related network requests use HTTPS with proper certificate validation. Verify the integrity of downloaded update packages using cryptographic signatures before applying them. Do not disable SSL/TLS validation in any network calls.
• Low · Omnibar Input Handling - Potential Path Injection — src/Files.App.Controls/Omnibar/. The Omnibar component (similar to an address bar) accepts user input that is likely used to navigate to file system paths or URLs. Without proper sanitization and validation, specially crafted inputs could lead to path traversal, unintended navigation to sensitive system paths, or protocol handler abuse (e.g., navigating to file://, ftp://, or custom protocol URIs). Fix: Validate and sanitize all user input from the Omnibar before using it for file system operations or navigation. Implement an allowlist of supported URI schemes. Canonicalize paths and ensure they stay within expected boundaries. Display warnings for potentially dangerous paths.
• Low · Missing Security Headers / Sandboxing Disclosure — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.