Movatterモバイル変換

No results found!

• Microservice Solution

• Exception Handling

• Localization

• Logging

• Object Extensions

• Options

ABP BLOB Storage system is also compatible to other ABP features likemulti-tenancy.

BLOB Storage Providers

The ABP has already the following storage provider implementations:

• File System: Stores BLOBs in a folder of the local file system, as standard files.
• Database: Stores BLOBs in a database.
• Azure: Stores BLOBs on theAzure BLOB storage.
• Aliyun: Stores BLOBs on theAliyun Storage Service.
• Minio: Stores BLOBs on theMinIO Object storage.
• Aws: Stores BLOBs on theAmazon Simple Storage Service.
• Google: Stores BLOBs on theGoogle Cloud Storage.
• Bunny: Stores BLOBs on theBunny.net Storage.

More providers will be implemented by the time. You canrequest it for your favorite provider orcreate it yourself andcontribute to the ABP.

Multiple providerscan be used together by the help of thecontainer system, where each container can uses a different provider.

BLOB storing system can not work unless youconfigure a storage provider. Refer to the linked documents for the storage provider configurations.

Installation

Volo.Abp.BlobStoring is the main package that defines the BLOB storing services. You can use this package to use the BLOB Storing system without depending a specific storage provider.

Use the ABP CLI to add this package to your project:

• Install theABP CLI, if you haven't installed it.
• Open a command line (terminal) in the directory of the.csproj file you want to add theVolo.Abp.BlobStoring package.
• Runabp add-package Volo.Abp.BlobStoring command.

If you want to do it manually, install theVolo.Abp.BlobStoring NuGet package to your project and add[DependsOn(typeof(AbpBlobStoringModule))] to theABP module class inside your project.

The IBlobContainer

IBlobContainer is the main interface to store and read BLOBs. Your application may have multiple containers and each container can be separately configured. But, there is adefault container that can be simply used byinjecting theIBlobContainer.

Example: Simply save and read bytes of a named BLOB

using System.Threading.Tasks;using Volo.Abp.BlobStoring;using Volo.Abp.DependencyInjection;namespace AbpDemo{    public class MyService : ITransientDependency    {        private readonly IBlobContainer _blobContainer;        public MyService(IBlobContainer blobContainer)        {            _blobContainer = blobContainer;        }        public async Task SaveBytesAsync(byte[] bytes)        {            await _blobContainer.SaveAsync("my-blob-1", bytes);        }                public async Task<byte[]> GetBytesAsync()        {            return await _blobContainer.GetAllBytesOrNullAsync("my-blob-1");        }    }}

This service saves the given bytes with themy-blob-1 name and then gets the previously saved bytes with the same name.

A BLOB is a named object andeach BLOB should have a unique name, which is an arbitrary string.

IBlobContainer can work withStream andbyte[] objects, which will be detailed in the next sections.

Saving BLOBs

SaveAsync method is used to save a new BLOB or replace an existing BLOB. It can save aStream by default, but there is a shortcut extension method to save byte arrays.

SaveAsync gets the following parameters:

• name (string): Unique name of the BLOB.
• stream (Stream) orbytes (byte[]): The stream to read the BLOB content or a byte array.
• overrideExisting (bool): Settrue to replace the BLOB content if it does already exists. Default value isfalse and throwsBlobAlreadyExistsException if there is already a BLOB in the container with the same name.

Reading/Getting BLOBs

• GetAsync: Only gets a BLOB name and returns aStream object that can be used to read the BLOB content. Alwaysdispose the stream after using it. This method throws exception, if it can not find the BLOB with the given name.
• GetOrNullAsync: In opposite to theGetAsync method, this one returnsnull if there is no BLOB found with the given name.
• GetAllBytesAsync: Returns abyte[] instead of aStream. Still throws exception if can not find the BLOB with the given name.
• GetAllBytesOrNullAsync: In opposite to theGetAllBytesAsync method, this one returnsnull if there is no BLOB found with the given name.

Deleting BLOBs

DeleteAsync method gets a BLOB name and deletes the BLOB data. It doesn't throw any exception if given BLOB was not found. Instead, it returns abool indicating that the BLOB was actually deleted or not, if you care about it.

Other Methods

• ExistsAsync method simply checks if there is a BLOB in the container with the given name.

About Naming the BLOBs

There is not a rule for naming the BLOBs. A BLOB name is just a string that is unique per container (and per tenant - see the "Multi-Tenancy" section). However, different storage providers may conventionally implement some practices. For example, theFile System Provider use directory separators (/) and file extensions in your BLOB name (if your BLOB name isimages/common/x.png then it is saved asx.png in theimages/common folder inside the root container folder).

Typed IBlobContainer

Typed BLOB container system is a way of creating and managingmultiple containers in an application;

• Each container is separately stored. That means the BLOB names should be unique in a container and two BLOBs with the same name can live in different containers without effecting each other.
• Each container can be separately configured, so each container can use a different storage provider based on your configuration.

To create a typed container, you need to create a simple class decorated with theBlobContainerName attribute:

using Volo.Abp.BlobStoring;namespace AbpDemo{    [BlobContainerName("profile-pictures")]    public class ProfilePictureContainer    {            }}

If you don't use theBlobContainerName attribute, ABP uses the full name of the class (with namespace), but it is always recommended to use a container name which is stable and does not change even if you rename the class.

Once you create the container class, you can injectIBlobContainer<T> for your container type.

Example: Anapplication service to save and read profile picture of thecurrent user

[Authorize]public class ProfileAppService : ApplicationService{    private readonly IBlobContainer<ProfilePictureContainer> _blobContainer;    public ProfileAppService(IBlobContainer<ProfilePictureContainer> blobContainer)    {        _blobContainer = blobContainer;    }    public async Task SaveProfilePictureAsync(byte[] bytes)    {        var blobName = CurrentUser.GetId().ToString();        await _blobContainer.SaveAsync(blobName, bytes);    }        public async Task<byte[]> GetProfilePictureAsync()    {        var blobName = CurrentUser.GetId().ToString();        return await _blobContainer.GetAllBytesOrNullAsync(blobName);    }}

IBlobContainer<T> has the same methods with theIBlobContainer.

It is a good practice toalways use a typed container while developing re-usable modules, so the final application can configure the provider for your container without effecting the other containers.

The Default Container

If you don't use the generic argument and directly inject theIBlobContainer (as explained before), you get the default container. Another way of injecting the default container is usingIBlobContainer<DefaultContainer>, which returns exactly the same container.

The name of the default container isdefault.

Named Containers

Typed containers are just shortcuts for named containers. You can inject and use theIBlobContainerFactory to get a BLOB container by its name:

public class ProfileAppService : ApplicationService{    private readonly IBlobContainer _blobContainer;    public ProfileAppService(IBlobContainerFactory blobContainerFactory)    {        _blobContainer = blobContainerFactory.Create("profile-pictures");    }    //...}

IBlobContainerFactory

IBlobContainerFactory is the service that is used to create the BLOB containers. One example was shown above.

Example: Create a container by name

var blobContainer = blobContainerFactory.Create("profile-pictures");

Example: Create a container by type

var blobContainer = blobContainerFactory.Create<ProfilePictureContainer>();

You generally don't need to use theIBlobContainerFactory since it is used internally, when you inject aIBlobContainer orIBlobContainer<T>.

Configuring the Containers

Containers should be configured before using them. The most fundamental configuration is toselect a BLOB storage provider (see the "BLOB Storage Providers" section above).

AbpBlobStoringOptions is theoptions class to configure the containers. You can configure the options inside theConfigureServices method of yourmodule.

Configure a Single Container

Configure<AbpBlobStoringOptions>(options =>{    options.Containers.Configure<ProfilePictureContainer>(container =>    {        //TODO...    });});

This example configures theProfilePictureContainer. You can also configure by the container name:

Configure<AbpBlobStoringOptions>(options =>{    options.Containers.Configure("profile-pictures", container =>    {        //TODO...    });});

Configure the Default Container

Configure<AbpBlobStoringOptions>(options =>{    options.Containers.ConfigureDefault(container =>    {        //TODO...    });});

There is a special case about the default container; If you don't specify a configuration for a container, itfallbacks to the default container configuration. This is a good way to configure defaults for all containers and specialize configuration for a specific container when needed.

Configure All Containers

Configure<AbpBlobStoringOptions>(options =>{    options.Containers.ConfigureAll((containerName, containerConfiguration) =>    {        //TODO...    });});

This is a way to configure all the containers.

The main difference from configuring the default container is thatConfigureAll overrides the configuration even if it was specialized for a specific container.

Multi-Tenancy

If your application is set as multi-tenant, the BLOB Storage systemworks seamlessly with themulti-tenancy. All the providers implement multi-tenancy as a standard feature. Theyisolate BLOBs of different tenants from each other, so they can only access to their own BLOBs. It means you can use thesame BLOB name for different tenants.

If your application is multi-tenant, you may want to controlmulti-tenancy behavior of the containers individually. For example, you may want todisable multi-tenancy for a specific container, so the BLOBs inside it will beavailable to all the tenants. This is a way to share BLOBs among all tenants.

Example: Disable multi-tenancy for a specific container

Configure<AbpBlobStoringOptions>(options =>{    options.Containers.Configure<ProfilePictureContainer>(container =>    {        container.IsMultiTenant = false;    });});

If your application is not multi-tenant, no worry, it works as expected. You don't need to configure theIsMultiTenant option.

Extending the BLOB Storing System

Most of the times, you won't need to customize the BLOB storage system exceptcreating a custom BLOB storage provider. However, you can replace any service (injected viadependency injection), if you need. Here, some other services not mentioned above, but you may want to know:

• IBlobProviderSelector is used to get aIBlobProvider instance by a container name. Default implementation (DefaultBlobProviderSelector) selects the provider using the configuration.
• IBlobContainerConfigurationProvider is used to get theBlobContainerConfiguration for a given container name. Default implementation (DefaultBlobContainerConfigurationProvider) gets the configuration from theAbpBlobStoringOptions explained above.

BLOB Storing vs File Management System

Notice that BLOB storing is not a file management system. It is a low level system that is used to save, get and delete named BLOBs. It doesn't provide a hierarchical structure like directories, you may expect from a typical file system.

If you want to create folders and move files between folders, assign permissions to files and share files between users then you need to implement your own application on top of the BLOB Storage system.

See Also

• Creating a custom BLOB storage provider

Thank you for your valuable feedback!

Please note that although we cannot respond to feedback, our team will use your comments to improve the experience.