Please note that version 9 is still in beta. For documentation on the latest stable release, please change to version 8.
Contribute to Docs Contribute to Docs

Azure Blob Storage

TheĀ Azure Blob Storage handles uploaded media by storing the uploaded files in an Azure Storage Service. If you're hosting your web application in Azure this has several benefits.

  • Dedicated storage is much cheaper than App Service storage.
  • Traffic from dedicated storage is much cheaper the App Service bandwidth.
  • Media files are distributed and is not stored together with the web application.
  • It's very easy to connect Azure CDN to Blob Storage.

As the media files are stored in a central location this works well when the different components of the application (such as client and manager) are deployed to different locations.

Installation

Azure Blob Storage can be installed by adding the NuGet package:

PM> install-package Piranha.Azure.BlobStorage

Registering The Service

You register Azure Blob Storage with the default configuration in ConfigureServices() with the following code:

services.AddPiranhaBlobStorage(credentials);

Manual configuration

The storage credentials can be created manually by providing the storage service name and key.

var credentials = new StorageCredentials(storageName, storageKey);

Using appsettings.json

You can easily configure your credentials from your appsettings.json by adding a section like this:

{
    "Storage": {
        "Name": "MyStorageName",
        "Key": "MyStorageKey"
    }
}

Given that you've setup your app configuration you can then access it like this from your ConfigureServices.

public class Startup
{
    public IConfiguration Configuration { get; private set; }

    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        ...

        services.AddPiranhaBlobStorage(new StorageCredentials(
            Configuration["Storage:Name"],
            Configuration["Storage:Key"]
        ));

        ...
    }
}

Using Connection String

You can also register the Blog Storage using its Connection String which can be found in the Azure portal by clicking Access Keys.

services.AddPiranhaBlobStorage(myConnectionString);

Additional Configuration

When registering the service you have access to some configuration options to customize the storage to your needs.

Container Name
services.AddPiranhaBlobStorage(credentials, containerName: "dev");

The container name in the Storage Service where uploaded media assets will be stored. The container name defaults to uploads and will create a new container with the same name if it doesn't exist.

To use an already existing container, make sure the access level should is set to Blob (anonymous access for blobs only) to ensure the files are publically available.

The folder structure in the media manager is maintained in the database and not the file storage, so changing this setting after uploading files or seeding example data will break the references to files and they will need to be re-uploaded.

Naming

You can change how unique names are generated for uploaded media files. By default a Guid is added to the beginning of the filename in order to ensure that it is unique, but this can be changed so that files are stored in a folder with a Guid based name.

services.AddPiranhaBlobStorage(naming: naming: Piranha.Azure.BlobStorageNaming.UniqueFolderNames);
Scope
services.AddPiranhaBlobStorage(credentials, scope: ServiceLifetime.Scoped);

By default the service is registered as a Singleton, but in some cases you might want to handle it differently in your application.