uTPro.Feature.FileManager 4.0.0

uTPro File Manager & Media Cleanup for Umbraco

A powerful File Manager and Media Cleanup toolkit for the Umbraco 16+ backoffice, on two workspace tabs. Browse, upload, download, edit, preview, rename and delete server files — and scan the media library to recycle, restore or delete unused, broken, duplicate, orphaned, large and disallowed media, all from within the backoffice.

Installation

dotnet add package uTPro.Feature.FileManager

No configuration needed — auto-registers via Umbraco IComposer. After installation, navigate to Settings → File Manager in the backoffice.

Features

File Browsing

• Windows Explorer-style navigation with back, reload, and breadcrumb path bar
• Paginated file listing (100 items per page) with "Load more" for large directories
• Real-time search with debounce filtering
• URL state persistence — reload the page and return to the same folder/file
• Umbraco native icons for file types

File Operations

• Upload files via button or drag & drop
• Download files directly from the file list or file view
• Create new folders and empty files
• Rename files and folders (with live reload in file view)
• Delete files and folders (single or bulk selection)
• Import file via URL — fetch a remote file and save it to the current folder
• Extract ZIP — select .zip files and extract them in place

Code Editor

• Built-in Monaco Editor (via Umbraco's umb-code-editor) with syntax highlighting
• Supports: JavaScript, TypeScript, JSON, HTML, CSS, SCSS, Razor, C#, XML, YAML, Markdown, SQL, and more
• Unsaved changes detection with browser close/navigate warning
• Ctrl+S keyboard shortcut to save

Media Preview

• Inline preview for images (JPG, PNG, GIF, SVG, WebP, BMP, ICO)
• Video player for MP4, WebM, OGG
• Audio player for MP3, WAV, OGG
• PDF viewer via embedded iframe
• Correct MIME types for inline rendering

Media Cleanup (v4.0.0)

• Lives on its own workspace tab next to File Manager (Settings → File Manager → Media Cleanup). Opening the tab scans automatically and shows an overview of cards — one per category with a live count; click a card to drill into that category. A breadcrumb (All categories › <Category>) navigates back.
• Reports media across seven categories, each with a live count:
  • Unused media — media items that no content/entity references (best-effort via Umbraco tracked references)
  • Broken media — media items whose backing file is missing on disk/storage
  • Duplicates — media items whose files share the same SHA-256 content hash
  • Orphaned files — files in the media file system not referenced by any media item
  • Large files — files at or above a configurable size threshold (default 100 MB), sorted largest first
  • Recycle Bin — media items currently in the Umbraco media recycle bin
• Actions per row (require Media section access; Admins always qualify):
  • Media-backed rows (Unused/Broken/Duplicates/Large) → Move to recycle bin (safe, recoverable; Umbraco handles permanent deletion + file cleanup when the bin is emptied)
  • Orphaned files → Delete file directly from the media file system (no media node to recycle)
  • Recycle Bin rows → Restore (back to the media root) or Delete permanently; plus an Empty recycle bin action for the whole bin
• Bulk actions — tick rows to act on many at once (Recycle/Delete for the current category, or Restore/Delete for the Recycle Bin)
• Smart duplicates — in the Duplicates tab, Recycle dupes (keep 1) recycles every copy except the first in each hash group
• Preview — click an image/media row to preview it (streamed via the media file system) before deciding
• Cached scans — results are cached briefly (default 30s, configurable) so switching tabs is fast; a forced reload or any action re-scans
• Scan mode reuses the same paginated list ("Load more", 100 per page); the top bar Home button (or Exit in the footer) returns to normal File Manager
• Uses Umbraco's media file system abstraction, so it works with any storage provider (physical disk, Azure Blob, S3, …)
• Scanning (the report) is visible to any Settings user; actions are gated on the current user's Media permission. Treat "Unused" as a suggestion, since references made only in free-form markup (rich text, templates, CSS/JS) may not be tracked — recycling is preferred over permanent deletion so items stay recoverable

Security & Permissions

• Settings section access required to view the dashboard
• Admin — full access: browse entire server root (ContentRootPath), create, edit, rename, delete, upload, extract
• Settings (non-admin) — browse wwwroot/ tree only (view folder structure, check if files exist — no file actions)
• Settings + Sensitive Data — browse wwwroot/ + view/edit/download file content
• Write operations (create, rename, delete, upload, extract ZIP, import URL) — Admin only
• Media Cleanup — the scan report is visible to any Settings user; its destructive actions (recycle/restore/delete/empty/delete-orphan) require Media section access (Admins always qualify)
• Non-admin users are jailed to wwwroot/ — cannot access appsettings.json, web.config, or any files outside wwwroot
• Protected files: web.config, appsettings.json, appsettings.development.json cannot be modified or deleted
• Path traversal protection on all endpoints
• Upload validation — configurable maximum size plus optional allow-list / block-list of extensions (see Configuration), enforced on both file upload and import-from-URL
• SSRF protection on Import via URL — the supplied URL must use http/https, and any URL whose host resolves to a loopback, private, link-local, or reserved address (e.g. the cloud metadata endpoint 169.254.169.254) is rejected. Requests go through IHttpClientFactory to avoid socket exhaustion.

UI

• Windows Explorer-style navigation bar (back, reload, home, breadcrumb path bar, search)
• Sticky toolbar — the navigation bar stays pinned to the top while scrolling long file lists, flush with the section header on an opaque surface
• Workspace footer actions — primary actions live in the Umbraco workspace footer for a clean, uncluttered toolbar:
  • Browsing: New ▾ menu (Upload, New Folder, New File, Import via URL), bulk Delete, Extract Zip, and a live item counter
  • File open: Save, Actions ▾ (Download, Rename, Delete), an Unsaved badge, plus file size and type
• Footer actions respect the current user's role — non-admin users never see write actions
• Multi-select with checkbox for bulk delete and zip extract
• Responsive layout with Umbraco UI Library (UUI) components

Configuration

No configuration is required — the package ships with safe defaults. To customize the upload limits, add an optional uTPro:Feature:FileManager section to appsettings.json:

{
  "uTPro": {
    "Feature": {
      "FileManager": {
        "MaxUploadSizeMB": 50,
        "AllowedUploadExtensions": [],
        "BlockedUploadExtensions": [ ".exe", ".dll", ".bat" ],
        "MediaLargeFileThresholdMB": 100,
        "MediaScanCacheSeconds": 30
      }
    }
  }
}

The upload limits apply to write operations only and are enforced server-side, independent of any client-side checks.

Compatibility

The package multi-targets net9.0 (Umbraco 16) and net10.0 (Umbraco 17 & 18); a single install picks the right build for your project automatically.

Screenshots

v4.0.0 — Two workspace tabs: File Manager & Media Cleanup

File Manager tab — browse, edit, upload, and manage server files

Media Cleanup tab — overview cards per category (Unused, Broken, Duplicates, Orphaned, Large, Disallowed, Recycle Bin); click a card to drill in and act

uTPro.Feature.FileManager - v2.0.0

Admin view — full access to browse, edit, upload, and manage all server files

Code editor with syntax highlighting (Monaco) and file actions menu

Select and extract ZIP files directly in the backoffice

Paginated loading — handles 2000+ files without UI lag

Create new files, folders, or import from URL

Non-admin users are restricted to wwwroot only

Sensitive Data role — read-only access to edit and view all files

Development

git clone https://github.com/T4VN/uTPro.Feature.FileManager.git
cd uTPro.Feature.FileManager
dotnet run --project src/uTPro.Feature.FileManager.TestSite

Navigate to https://localhost:54740/umbraco, log in, go to Settings → File Manager.

Project Structure

src/uTPro.Feature.FileManager/
├── Controllers/
│   └── FileManagerApiController.cs    # API endpoints with role-based access
├── Services/
│   ├── IFileManagerService.cs         # Service interface
│   ├── FileManagerService.cs          # File operations implementation
│   ├── IMediaScanService.cs           # Media Cleanup scan interface
│   ├── MediaScanService.cs            # Media Cleanup scan implementation
│   └── FileManagerComposer.cs         # DI registration
├── Models/
│   ├── FileItemViewModel.cs           # File/folder view model
│   ├── FileManagerOptions.cs          # Configurable options (upload limits, large-file threshold, scan cache)
│   ├── MediaScanItem.cs               # Media Cleanup row view model
│   ├── MediaScanResult.cs             # Media Cleanup scan result + counts
│   ├── MediaActionRequest.cs          # Recycle/restore/delete/delete-orphan request
│   ├── MediaActionResult.cs           # Cleanup action outcome (success + message)
│   ├── MediaFileContent.cs            # Raw bytes for media preview
│   └── ...                            # Browse/rename/create/upload request + result DTOs
└── wwwroot/
    ├── index.js                       # Main Lit Element dashboard view
    ├── footer.js                      # Workspace footer app (New/Save/Actions/bulk + item count)
    ├── context.js                     # Shared workspace context bridging view ↔ footer
    ├── helpers.js                     # Constants, utilities, icon mapping
    ├── styles.js                      # CSS styles
    └── umbraco-package.json           # Umbraco package manifest

Changelog

4.0.0

• Media Cleanup is now its own workspace tab next to File Manager (no more "Scan Media" button / in-place mode toggle). Switch tabs to move between managing files and cleaning up media.
• Overview cards — opening the Media Cleanup tab auto-scans and shows a card per category (Unused, Broken, Duplicates, Orphaned, Large, Disallowed, Recycle Bin) with live counts and severity colors. Click a card to drill in; a breadcrumb navigates back. Row actions and bulk actions stay in the footer (consistent with the Files tab).
• Jump to Media — media-backed rows link to their node in the Media section (name link + action button), opening in a new tab. Especially handy for Broken media.
• No breaking server API changes. Requires a backoffice hard-refresh after upgrade (new workspace manifest).

3.1.1

• New "Disallowed" scan category — physical media files whose extension is in Umbraco's Content:DisallowedUploadedFileExtensions (potential security risk), with recycle/delete actions.
• Ignore list (IgnoredMediaIds) to silence false positives in Unused/Large; scan guardrails (MediaScanMaxFiles, MediaScanTimeBudgetSeconds) stop very large scans early with an on-screen notice.
• Upload validation unions with Umbraco — BlockedUploadExtensions ∪ Content:DisallowedUploadedFileExtensions always reject; when AllowedUploadExtensions is set it unions with Content:AllowedUploadedFileExtensions. Empty allow-list = allow all (site files like css/js/cshtml still upload; Umbraco's media-only whitelist is not inherited when empty).

3.1.0

• Media Cleanup actions — the scan is no longer report-only. Each row now has actions: media-backed rows can be moved to the recycle bin, orphaned files can be deleted from the media file system, and a new Recycle Bin category lets you Restore, Delete permanently, or Empty recycle bin.
• Permissions — the scan report is visible to any Settings user, while the destructive actions (recycle/restore/delete/empty) require the current user to have Media section access (Admins always qualify).
• Bulk actions (row checkboxes), Smart duplicates ("keep 1 per group"), inline media preview, and cached scans (MediaScanCacheSeconds, default 30s) for fast tab switching.
• Recycle Bin added as a sixth scan category (after Large files).
• Auto-refresh on tab click — switching category tabs re-runs the scan so counts stay current.
• Media lookups now resolve by key via IIdKeyMap + GetById(int) for compatibility across Umbraco 16/17/18 (Umbraco 18 removed IMediaService.GetById(Guid) from the interface). No breaking API changes to existing endpoints.

3.0.0

• Media Cleanup scan — a new Scan Media action in the File Manager footer reports media across five categories, each with a live count and filter tab: Unused media, Broken media, Duplicates, Orphaned files, and Large files. Results reuse the paginated list ("Load more"), and Home/Exit returns to the normal File Manager.
• Configurable large-file threshold via uTPro:Feature:FileManager:MediaLargeFileThresholdMB (default 100 MB). See Configuration.
• Scanning goes through Umbraco's media file system abstraction, so it works with any storage provider (disk, Azure Blob, S3, …).
• Admin only and report-only — no destructive actions. No breaking API changes to existing endpoints.

2.1.0

• Configurable upload limits via the uTPro:Feature:FileManager section — MaxUploadSizeMB, an AllowedUploadExtensions allow-list, and a BlockedUploadExtensions block-list — enforced on both file upload and import-from-URL. See Configuration.
• Import via URL hardening — now uses IHttpClientFactory and includes an SSRF guard that rejects URLs resolving to loopback/private/link-local/reserved addresses and any non-http(s) scheme.
• No breaking API changes.

2.0.1

• Maintenance release — clean rebuild from a wiped output to guarantee the shipped assembly is current (packaging now goes through a deterministic clean-pack step). No source or API changes versus 2.0.0.

2.0.0

• Support for Umbraco 16, 17 and 18 (multi-target net9.0 / net10.0).
• Hardened path-traversal root check and upload filename sanitization.
• No breaking API changes.

1.x

• Initial releases — file browsing, upload/download, code editor, media preview, and role-based access for Umbraco 16.

License

MIT

Author

T4VN — GitHub