Getting Started

Friendly Media helps editors manage Umbraco media more efficiently by automatically generating SEO-friendly URLs, surfacing potential issues through helpful warning badges, and protecting referenced media from accidental deletion.

Installation

Install Friendly Media from NuGet, either using the Package Manager Console or the .NET CLI:

dotnet add package Rivlo.FriendlyMedia

Configuration

Default configuration settings are automatically applied.

If you need to customise behaviour, add or adjust the following section in your appsettings.json:

"Rivlo": {
  "FriendlyMedia": {
    "EnableStreaming": false,
    "StorageMode": "Database"
    "DeletionGuard": { 
        "Enabled": true, 
        "UseRelations": true, 
        "UseUdiExamine": true 
    },
    "RestoreFromBin": { 
        "Enabled": true, 
        "FallbackParentId": -1 
    }
  }
}

Configuration details:

EnableStreaming

Switch to direct streaming of media files. By default Friendly Media redirects to the original Umbraco media URL.

⚠️ Important:

When EnableStreaming is set to true, Friendly Media streams files directly from storage to preserve stable, friendly URLs.

This mode bypasses Umbraco’s ImageSharp processing and caching, so query-string image transformations (e.g. ?width=400) will not be applied and files are served at their original size. Use this mode with caution and only when you need direct file streaming and are not relying on Umbraco’s built-in image processing pipeline.

StorageMode

Choose how generated URLs are stored. Default is Database but you can also use Json.

DeletionGuard

• Enabled: Prevents deletion of media referenced in content or via URLs.
• UseRelations: Checks Umbraco relations to detect linked media.
• UseUdiExamine: Uses Examine to identify references based on UDIs and URLs.

RestoreFromBin

• Enabled: Adds a “Restore from Bin” option to recover deleted media items.
• FallbackParentId: Optional ID to restore items to if their original parent no longer exists (-1 = root).

Enable Middleware

Friendly Media handles friendly URLs and redirects using middleware.

To activate this functionality, register the middleware before Umbraco’s own pipeline (app.AddUmbraco()) in your Program.cs file:

app.UseFriendlyMediaMiddleware();