UmbracoFileSystemProviders.Azure v1

This version is for Umbraco v7 only. For the v2 package for Umbraco v8 please visit the develop-umbraco-version-8 branch

An Azure Blob Storage IFileSystem provider for Umbraco 7.1.9+. Used to offload static files in the media section to the cloud.

Designed to supersede UmbracoAzureBlobStorage by Dirk Seefeld (With his blessing) this package allows the storage and retrieval of media items using Azure Blob Storage while retaining the relative paths to the files expected in the back office.

Installation

Both NuGet and Umbraco packages are available. If you use NuGet but would like the benefit of the Umbraco configuration wizard you can install the Umbraco package first, use the wizard, then install the NuGet package, the configuration will be maintained.

NuGet Packages	Version
Release
Pre-release

Umbraco Packages
Release
Pre-release

Manual build

If you prefer, you can compile UmbracoFileSystemProviders.Azure yourself, you'll need:

• Visual Studio 2015 (or above)

To clone it locally click the "Clone in Windows" button above or run the following git commands.

git clone https://github.com/JimBobSquarePants/UmbracoFileSystemProviders.Azure
cd UmbracoFileSystemProviders.Azure
.\build.cmd

In the interim code reviews and pull requests would be most welcome!

Usage

Note: Upon release most of configuration this will be automated.

Update ~/Config/FileSystemProviders.config replacing the default provider with the following:

<?xml version="1.0"?>
<FileSystemProviders>
  <Provider alias="media" type="Our.Umbraco.FileSystemProviders.Azure.AzureBlobFileSystem, Our.Umbraco.FileSystemProviders.Azure">
    <Parameters>
      <add key="containerName" value="media" />
      <add key="rootUrl" value="https://[myAccountName].blob.core.windows.net/" />
      <add key="connectionString" value="DefaultEndpointsProtocol=https;AccountName=[myAccountName];AccountKey=[myAccountKey]"/>
      <!--
        Optional configuration value determining the maximum number of days to cache items in the browser.
        Defaults to 365 days.
      -->
      <add key="maxDays" value="365" />
      <!--
        When true this allows the VirtualPathProvider to use the default "media" route prefix regardless 
        of the container name.
      -->
      <add key="useDefaultRoute" value="true" />
      <!--
        When true blob containers will be private instead of public what means that you can't access the original blob file directly from its blob url.
      -->
      <add key="usePrivateContainer" value="false" />
    </Parameters>
  </Provider>
</FileSystemProviders>

Developmental mode configuration using the Azure Storage Emulator for testing is as follows:

<?xml version="1.0"?>
<FileSystemProviders>
  <Provider alias="media" type="Our.Umbraco.FileSystemProviders.Azure.AzureBlobFileSystem, Our.Umbraco.FileSystemProviders.Azure">
    <Parameters>
      <add key="containerName" value="media" />
      <add key="rootUrl" value="http://127.0.0.1:10000/devstoreaccount1/" />
      <add key="connectionString" value="UseDevelopmentStorage=true"/>
    </Parameters>
  </Provider>
</FileSystemProviders>

Additionally the provider can be further configured with the following application setting in the web.config.

<?xml version="1.0"?>
<configuration>
  <appSettings>
    <!--Disables the built in Virtual Path Provider which allows for relative paths-->
    <add key="AzureBlobFileSystem.DisableVirtualPathProvider" value="true" />
    <!--
      Enables the development mode for testing. Addition changes to the FileSystemProviders.config are also required
    -->
    <add key="AzureBlobFileSystem.UseStorageEmulator" value="true" />
  </appSettings>
</configuration>

Configuration via Web.Config

Available in v0.5.4+

Optionally instead of having the configuration in FileSystemProviders.config it can be moved to Web.config

In FileSystemProviders.config remove the default parameters and add a new one with the key alias, the value should match the provider alias

<?xml version="1.0"?>
<FileSystemProviders>
  
  <!-- Media -->
  <Provider alias="media" type="Our.Umbraco.FileSystemProviders.Azure.AzureBlobFileSystem, Our.Umbraco.FileSystemProviders.Azure">
  	<Parameters>
  		<add key="alias" value="media"/>
  	</Parameters>
  </Provider>
   
</FileSystemProviders>

In Web.config create the new application keys and post fix each key with the alias defined in FileSystemProviders.config after a colon.

<add key="AzureBlobFileSystem.ConnectionString:media" value="DefaultEndpointsProtocol=https;AccountName=[myAccountName];AccountKey=[myAccountKey]" />
<add key="AzureBlobFileSystem.ContainerName:media" value="media" />
<add key="AzureBlobFileSystem.RootUrl:media" value="https://[myAccountName].blob.core.windows.net/" />
<add key="AzureBlobFileSystem.MaxDays:media" value="365" />
<add key="AzureBlobFileSystem.UseDefaultRoute:media" value="true" />
<add key="AzureBlobFileSystem.UsePrivateContainer:media" value="false" />

Configuration for Azure Key Vault

For Azure Key Vault only the key values in the Web.config should use '-', rather than a '.' or ':' as shown below

<add key="AzureBlobFileSystem-ConnectionString-media" value="DefaultEndpointsProtocol=https;AccountName=[myAccountName];AccountKey=[myAccountKey]" />
<add key="AzureBlobFileSystem-ContainerName-media" value="media" />
<add key="AzureBlobFileSystem-RootUrl-media" value="https://[myAccountName].blob.core.windows.net/" />
<add key="AzureBlobFileSystem-MaxDays-media" value="365" />
<add key="AzureBlobFileSystem-UseDefaultRoute-media" value="true" />
<add key="AzureBlobFileSystem-UsePrivateContainer-media" value="false" />

Virtual Path Provider

By default the plugin will serve files transparently from your domain or serve media directly from Azure. This is made possible by using a custom Virtual Path Provider included and automatically initialised upon application startup. This can be disable by adding the configuration setting noted above.

Note: Virtual Path Providers may affect performance/caching depending on your setup as the process differs from IIS's unmanaged handler. Virtual files sent via the provider though are correctly cached in the browser so this shouldn't be an issue. VVP providers also don't work with Precompiled sites or when used in a virtual directory/application.

The following configuration is required in your web.config to enable static file mapping in IIS Express.

<?xml version="1.0"?>
  <configuration>
    <location path="Media">
      <system.webServer>
        <handlers>
          <remove name="StaticFileHandler" />
          <add name="StaticFileHandler" path="*" verb="*" preCondition="integratedMode" type="System.Web.StaticFileHandler" />
        </handlers>
      </system.webServer>
    </location>
  </configuration>

For Umbraco v7.5+ you must add the the StaticFileHandler to the new Web.config inside the Media folder instead of the root one or the VPP will not work!

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<system.webServer>
		<handlers>
			<clear />
			<add name="StaticFileHandler" path="*" verb="*" preCondition="integratedMode" type="System.Web.StaticFileHandler" />
			<add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
		</handlers>
	</system.webServer>
</configuration>

Combining with ImageProcessor

As of ImageProcessor.Web version 4.3.2 a new IImageService implementation has been available called CloudImageService. To enable that service and pull images directly from the cloud simply install the configuration package and replace the CloudImageServicesetting with the following:

<?xml version="1.0"?>
<security>
  <services>
    <service name="LocalFileImageService" type="ImageProcessor.Web.Services.LocalFileImageService, ImageProcessor.Web"/>
    <service prefix="media/" name="CloudImageService" type="ImageProcessor.Web.Services.CloudImageService, ImageProcessor.Web">
      <settings>
        <setting key="MaxBytes" value="8194304"/>
        <setting key="Timeout" value="30000"/>
        <setting key="Host" value="https://[myAccountName].blob.core.windows.net/media/"/>
      </settings>
    </service>
  </services>  
</security>

Note The CloudImageServiceis not compatible with the FileSystemProvider when using private storage. You will have to build your own IImageService implementation.

If using a version of ImageProcessor.Web version 4.5.0 the configuration details will need to be configured as follows:

<?xml version="1.0"?>
<security>
  <services>
    <service name="LocalFileImageService" type="ImageProcessor.Web.Services.LocalFileImageService, ImageProcessor.Web"/>
    <service prefix="media/" name="CloudImageService" type="ImageProcessor.Web.Services.CloudImageService, ImageProcessor.Web">
      <settings>
        <setting key="Container" value="media"/>
        <setting key="MaxBytes" value="8194304"/>
        <setting key="Timeout" value="30000"/>
        <setting key="Host" value="https://[myAccountName].blob.core.windows.net/media"/>
      </settings>
    </service>
  </services>  
</security>

Be sure to install the AzureBlobCache plugin to get the most out of the package.

Authors

• James Jackson-South
• Dirk Seefeld
• Lars-Erik Aabech
• Jeavon Leopold

Thanks

• Elijah Glover for writing the Umbraco S3 Provider which provided inspiration and some snazzy unit testing code for this project.