API reference for blob storage
The Sitecore Azure Blob Storage module consists of the following assembly:
-
Sitecore.Framework.Data.Blobs
- provides theAzureStorageBlobProvider
class, which allows APIs to work with blob storage.
Sitecore exposes a BlobStorage
API to include the underlying blob providers (for example, AzureStorageBlobProvider
), and provides convenient APIs to work with blob storage. By default, the BlobStorage
API consists of the following assemblies:
-
Sitecore.Framework.Data.Blobs.Abstractions
- provides abstractions to implement blob providers for the Sitecore Blob Storage module. -
Sitecore.Framework.Data.Blobs
- provides convenient APIs so you can work with blob storage without having to know about the blob providers configured in Sitecore.
BlobStorage APIs
The databases in Sitecore can use one or more storage for blob storage. In Sitecore, the Database.BlobStorage
property includes a list of blob providers that work with the Sitecore databases. The property also lists APIs that you can use to work as extension methods with blob storage, without having to know about the blob providers configured in Sitecore.
Use the following code to access BlobStorage
in Sitecore:
BlobStorage blobStorage = Database.BlobStorage;
The following class name examples demonstrate how to use the Sitecore APIs from BlobStorage
extensions:
Method |
|
Description |
Use this API with the Blob ID to check whether a a blob exists in a Blob Storage account. |
Example |
RequestResponseshell
|
Method |
|
Description |
Use this API with the Blob ID to get a specific blob from Blob Storage. |
Example |
RequestResponseshell
|
Method |
|
Description |
Use this API with the Blob ID to remove the blob from Blob Storage. |
Example |
RequestResponseshell
|
Method |
|
Description |
Use this API with the Blob ID to save the blob in Blob Storage. |
Example |
RequestResponseshell
|
Remove orphaned blobs
Sitecore's blob storage garbage collection feature helps you delete orphaned blobs from Sitecore. Initiate the deletion by using the following method: Sitecore.Data.DefaultDatabase.BlobStorage.CleanupOrphanBlobs
.
For example:
var database = Sitecore.Configuration.Factory.GetDatabase("master");
database.BlobStorage.CleanupOrphanBlobs();
AzureStorageBlobProvider APIs
There are a few different ways you can access the blob provider directly, if necessary:
-
Example 1:
RequestResponseshellIBlobProviderAsync blobProvider = blobStorage.GetBlobProvider<AzureStorageBlobProvider>();
-
Example 2:
RequestResponseshellIBlobProviderAsync blobProvider = blobStorage.GetDefaultBlobProvider<IBlobProviderAsync>();
-
Example 3:
RequestResponseshellBlobIdentifier blobId = new BlobIdentifier("B4D19D07-B3EB-4F7D-98EC-8BCB41CCC58E"); IBlobProviderAsync blobProvider = blobStorage.GetBlobProvider<IBlobProviderAsync>(blobId);
This following class name examples demonstrate how to use the Sitecore APIs from BlobProvider
methods:
Method |
|
Description |
Use this API with the Blob ID to check whether the blob exists in Blob Storage. |
Example |
RequestResponseshell
|
Method |
|
Description |
Use this API with the Blob ID to get a specific blob from Blob Storage. |
Example |
RequestResponseshell
|
Method |
|
Description |
Use this API with the Blob ID to remove a blob from Blob Storage. |
Example |
RequestResponseshell
|
Method |
|
Description |
Use this API with the Blob ID to save a blob in Blob Storage. |
Example |
RequestResponseshell
|
Extend AzureStorageBlobProvider APIs
You can extend blob provider methods, for example, if you want to extend the GetBlob
API:
using Sitecore.Framework.Data.Blobs.Abstractions;
using Sitecore.Framework.Data.Blobs.Azure;
using System.IO;
namespace Documentation
{
public class ExtendGetBlob : AzureStorageBlobProvider
{
public ExtendGetBlob(string connectionStringName, IPagedListProvider usedBlobIdsPagedListProvider) :
base(connectionStringName, usedBlobIdsPagedListProvider)
{
}
public override Stream GetBlob(BlobIdentifier identifier)
{
var blobStream = base.GetBlob(identifier);
// Code to extend the GetBlob default behavior
return blobStream;
}
}
}
Create a new BlobProvider
You can create your own blob providers by using the Sitecore.Framework.Data.Blobs.Abstractions
APIs, for example, if you want to create an InMemoryBlobProvider
API:
using Sitecore.Framework.Conditions;
using Sitecore.Framework.Data.Blobs.Abstractions;
using System;
using System.Collections.Generic;
using System.IO;
namespace Documentation
{
public class InMemoryBlobProvider : IBlobProvider
{
private readonly string _scheme = "memoryblob";
private IDictionary<Uri, byte[]> blobs = new Dictionary<Uri, byte[]>();
private void ValidateIdentifier(BlobIdentifier identifier)
{
if (!CanHandle(identifier))
throw new InvalidOperationException(
$"The identifier '{identifier}' is not in acceptable format by this provider");
}
private byte[] GetBytes(Stream input)
{
using (MemoryStream ms = new MemoryStream())
{
input.CopyTo(ms);
return ms.ToArray();
}
}
public bool BlobExists(BlobIdentifier identifier)
{
Condition.Requires(identifier, nameof(identifier)).IsNotNull();
if (string.IsNullOrEmpty(identifier.ToString()))
{
return false;
}
ValidateIdentifier(identifier);
try
{
return blobs.ContainsKey(identifier.ToUri());
}
catch (Exception ex)
{
throw new BlobProviderException(ex.Message, ex.InnerException);
}
}
public bool CanHandle(BlobIdentifier identifier)
{
return (identifier != null) &&
Uri.TryCreate(identifier.ToString(), UriKind.Absolute, out Uri result) &&
result.Scheme != null &&
result.Scheme.Equals(_scheme, StringComparison.InvariantCultureIgnoreCase);
}
public BlobIdentifier CreateBlobIdentifier()
{
return new BlobIdentifier($"{_scheme}://{Guid.NewGuid()}");
}
public BlobIdentifier CreateBlobIdentifier(Guid guid)
{
Condition.Requires(guid, nameof(guid)).IsNotEqualTo(Guid.Empty);
return new BlobIdentifier($"{_scheme}://{guid}");
}
public Guid ToGuid(BlobIdentifier identifier)
{
Condition.Requires(identifier, nameof(identifier)).IsNotNull();
ValidateIdentifier(identifier);
return new Guid(new Uri(identifier.ToString()).Host);
}
public Stream GetBlob(BlobIdentifier identifier)
{
Condition.Requires(identifier, nameof(identifier)).IsNotNull();
if (string.IsNullOrEmpty(identifier.ToString()))
{
return null;
}
ValidateIdentifier(identifier);
try
{
if (blobs.ContainsKey(identifier.ToUri()))
{
return new MemoryStream(blobs[identifier.ToUri()]);
}
else
{
return null;
}
}
catch (Exception ex)
{
throw new BlobProviderException(ex.Message, ex.InnerException);
}
}
public void RemoveBlob(BlobIdentifier identifier)
{
Condition.Requires(identifier, nameof(identifier)).IsNotNull();
ValidateIdentifier(identifier);
if (blobs.ContainsKey(identifier.ToUri()))
{
blobs.Remove(identifier.ToUri());
}
}
public void SetBlob(Stream stream, BlobIdentifier identifier)
{
Condition.Requires(stream, nameof(stream)).IsNotNull();
Condition.Requires(identifier, nameof(identifier)).IsNotNull();
ValidateIdentifier(identifier);
blobs[identifier.ToUri()] = GetBytes(stream);
}
}
public static class BlobIdentifierExtensions
{
public static bool IsUri(this BlobIdentifier identifier)
{
if (identifier != null && !string.IsNullOrWhiteSpace(identifier.ToString()))
{
string blobId = identifier.ToString();
if (Uri.IsWellFormedUriString(blobId, UriKind.Absolute))
{
return true;
}
}
return false;
}
public static Uri ToUri(this BlobIdentifier identifier)
{
Condition.Requires(identifier, nameof(identifier)).IsNotNull();
if (!identifier.IsUri())
{
throw new ArgumentException($"Provided identifier {identifier.ToString()} is not a valid Uri.");
}
return new Uri(identifier.ToString());
}
}
}