Skip to content

Azure Media (OrchardCore.Media.Azure)

The Azure Media module enables support for storing assets in Microsoft Azure Blob Storage.

Azure Media Storage (OrchardCore.Media.Azure.Storage)

The feature replaces the default App_Data file based media store with an Azure Media Storage Provider.

Media is still served by the Orchard Core web site, and the Media Cache module takes responsibility for fetching media, on the fly, from the Azure Blob Storage Container.

This allows the Azure Media Storage feature to support image resizing on the fly.

The url generated by the AssetUrl helpers, points to the Orchard Core web site.

Configuration

The following configuration values are used by default and can be customized:

{
  "OrchardCore": {
    "OrchardCore_Media_Azure": {
      // Set to your Azure Storage account connection string.
      "ConnectionString": "", 
      // Set to the Azure Blob container name. A container name must be a valid DNS name and conform to Azure container naming rules eg. lowercase only.
      "ContainerName": "somecontainer",
      // Optionally, set to a path to store media in a subdirectory inside your container.
      "BasePath": "some/base/path",
       // Activates an event to create the container if it does not already exist.
      "CreateContainer": true,
      // Whether the 'Container' is deleted if the tenant is removed, false by default.
      "RemoveContainer": true,
      // Overrides auto-detection of Hierarchical Namespace (HNS / ADLS Gen2) support. Leave unset to
      // auto-detect. Set explicitly when account-level detection is unavailable, such as when
      // connecting with a container-scoped SAS token.
      "UseHierarchicalNamespace": true
    }
  }
}

Refer also to the Configuration Section, and the Media Section for other Media related configuration settings.

If the CreateContainer option is set to true an activating event will check on Startup for a valid connection string, and test that the container exists, creating if it does not. Set CreateContainer to false to disable this check if your container already exists.

If these are not present in appSettings.json, it will not enable the feature, and report an error message in the log file.

Hierarchical Namespace (ADLS Gen2) Support

Azure Media Storage supports Azure Storage accounts with Hierarchical Namespace (HNS), also known as Azure Data Lake Storage Gen2, in addition to standard flat-namespace (Gen1) accounts.

The store probes the storage account to auto-detect whether HNS is enabled. When it is, directory creation, directory deletion, and file moves use native Data Lake Storage APIs, which provide atomic moves and real (non-virtual) directories. On flat-namespace (Gen1) accounts, directories continue to be emulated with a marker file, matching the existing behavior.

Auto-detection requires storage account-level permissions and will fail if you connect with a container-scoped SAS token. In that case, set UseHierarchicalNamespace explicitly to true for a Gen2 account or false for a Gen1 account so the configured behavior is used when detection fails.

The Data Lake SDK derives the account's DFS endpoint from the configured connection string, so no separate DFS endpoint setting is required.

Templating Configuration

Optionally you may use liquid templating to further configure Azure Media Storage, perhaps creating a container per tenant, or a single container with a base path per tenant.

The ShellSettings property is made available to the liquid template. The ContainerName property and the BasePath property are the only templatable properties.

Note

When templating the ContainerName using {{ ShellSettings.Name }}, the tenant's name will be automatically lowercased, however, you must also make sure the ContainerName conforms to other Azure Blob naming conventions as set out in Azure's documentation.

Configuring a container per tenant

{
  "OrchardCore": {
    "OrchardCore_Media_Azure": {
      // Set to your Azure Storage account connection string.
      "ConnectionString": "", 
      // Optionally configure with liquid. A container name must be a valid DNS name and conform to Azure container naming rules eg. lowercase only.
      "ContainerName": "{{ ShellSettings.Name }}-media",
      // Optionally configure with liquid.
      "BasePath": "Media",
      "CreateContainer": true
    }
  }
}

Configuring a single container, with a base folder per tenant

{
  "OrchardCore": {
    "OrchardCore_Media_Azure": {
      // Set to your Azure Storage account connection string.
      "ConnectionString": "", 
      // Optionally configure with liquid. A container name must be a valid DNS name and conform to Azure container naming rules eg. lowercase only.
      "ContainerName": "somecontainer",
      // Optionally configure with liquid.
      "BasePath": "{{ ShellSettings.Name }}/Media",
      "CreateContainer": true
    }
  }
}

Note

Only the default Liquid filters and tags are available during parsing of the Liquid template. Extra filters like slugify will not be available.

Media Cache

The Media Cache feature will automatically be enabled when Azure Media Storage is enabled.

The Media Cache feature will cache files stored from Azure Blob Storage, to support image resizing.

The Media Cache feature allows Purging of the Media Cache files stored locally.

You might choose to use the Purging feature if you are fronting the media assets with a CDN. After allowing a long enough period of time for the CDN to have fetched a significant amount of Media assets, both resized, and full size, from the Media Cache you might consider purging the cache.

However please bear in mind that your CDN provider will likely have multiple Points of Presence worldwide, and each of these will maintain their own cache, so while a local CDN PoP might have the asset another PoP may not, until it is requested. At this stage the Media Cache will, if necessary, refetch the asset from Azure Blog Storage, on the fly, and provide it to the CDN PoP.

CDN providers also clear their caches at pre-determined times of their own devising, so while CDN's are a valuable caching and performance asset, it is important that they are always be able to re-fetch the source file, as and when required, which the Media Cache Module will automatically handle.

Note

The Media Feature is designed to support one storage provider at a time, whether that is local File Storage (the default), Azure Blob Storage, or Amazon S3 Storage.

Azure Media Image Cache (OrchardCore.Media.Azure.ImageCache)

The feature replaces the default local filesystem cache that stores resized images in the App_Data folder with an Azure Blob Storage cache. Depending on your use case, this can provide the following advantages:

  • Persistent image cache so you don't have to repeatedly resize images, even if the local file system of the web server is ephemeral. This helps if you use containers to host the app, or do clean deployments to the web server that remove all previously existing files.
  • Better performance if disk IO is a bottleneck: The local storage of the web server may be slow or access to it deliberately throttled, like it is the case with Azure App Services. Using Blob Storage can alleviate pressure on the local disk, leaving more resources available to serve other requests, as well as offer a higher request per second limit for image requests.

Note

Cache files are only removed for a tenant when removing the tenant itself if you use a separate container for each tenant.

Configuration

The following configuration values are used by default and can be customized:

{
  "OrchardCore": {
    "OrchardCore_Media_Azure_Image_Cache": {
        // Set to your Azure Storage account connection string.
        "ConnectionString": "", 
        // Set to the Azure Blob container name. A container name must be a valid DNS name and conform to Azure container naming rules eg. lowercase only.
        "ContainerName": "somecontainer",
        // Optionally, set to a path to store media in a subdirectory inside your container.
        "BasePath": "some/base/path",
        // Activates an event to create the container if it does not already exist.
        "CreateContainer": true,
        // Whether the 'Container' is deleted if the tenant is removed, false by default.
        "RemoveContainer": true,
        // Indicates whether to delete all files under the specified base path when the tenant is removed. This setting only takes effect if 'RemoveContainer' is set to false. Defaults to false.
        "RemoveFilesFromBasePath": true
    }
  }
}

Note

Templating the configuration and configuring a container per tenant work the same way as for Azure Media Storage; follow its documentation above.