mirror of https://github.com/abpframework/abp.git
maliming
6 years ago
committed by
GitHub
GitHub
7 changed files with 699 additions and 10 deletions
@ -1 +1,58 @@ |
|||
TODO... |
|||
# BLOB Storing Azure提供程序 |
|||
|
|||
BLOB存储Azure提供程序可以将BLOB存储在[Azure Blob storage](https://azure.microsoft.com/en-us/services/storage/blobs/)中. |
|||
|
|||
> 阅读[BLOB存储文档](Blob-Storing.md)了解如何使用BLOB存储系统. 本文档仅介绍如何为容器配置Azure提供程序. |
|||
|
|||
## 安装 |
|||
|
|||
使用ABP CLI添加[Volo.Abp.BlobStoring.Azure](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Azure)NuGet包到你的项目: |
|||
|
|||
* 安装 [ABP CLI](https://docs.abp.io/en/abp/latest/CLI), 如果你还没有安装. |
|||
* 在要添加 `Volo.Abp.BlobStoring.Azure` 包的 `.csproj` 文件目录打开命令行. |
|||
* 运行 `Volo.Abp.BlobStoring.Azure` 命令. |
|||
|
|||
如果要手动安装,在你的项目中安装 `Volo.Abp.BlobStoring.Azure` NuGet包然后将`[DependsOn(typeof(AbpBlobStoringAzureModule))]`添加到项目内的[ABP模块](Module-Development-Basics.md)类中. |
|||
|
|||
## 配置 |
|||
|
|||
如同[BLOB存储文档](Blob-Storing.md)所述,配置是在[模块](Module-Development-Basics.md)类的 `ConfigureServices` 方法完成的. |
|||
|
|||
**示例: 配置为默认使用Azure存储提供程序** |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containerscontainer.UseAzure(azure => |
|||
{ |
|||
azure.ConnectionString = "your azure connection string"; |
|||
azure.ContainerName = "your azure container name"; |
|||
azure.CreateContainerIfNotExists = false; |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
> 参阅[BLOB存储文档](Blob-Storing.md) 学习如何为指定容器配置提供程序. |
|||
|
|||
### 选项 |
|||
|
|||
* **ConnectionString** (string): 连接字符串包括应用程序在运行时使用共享密钥授权访问Azure存储帐户中的数据所需的授权信息. 请参考[Azure文档](https://docs.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string). |
|||
* **ContainerName** (string): 你可以在azure中指定容器名称. 如果没有指定它将使用 `BlogContainerName` 属性定义的BLOB容器的名称(请参阅[BLOB存储文档](Blob-Storing.md)). 请注意Azure有一些**命名容器的规则**,容器名称必须是有效的DNS名称,[符合以下命名规则](https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata#container-names): |
|||
* 容器名称必须以字母或数字开头或结尾,并且只能包含字母,数字和破折号(-)字符. |
|||
* 每个破折号(-)必须紧跟在字母或数字之后;容器名称中不允许使用连续的破折号. |
|||
* 容器名称中的所有字母都必须**小写**. |
|||
* 容器名称的长度必须在**3**到**63**个字符之间. |
|||
* **CreateContainerIfNotExists** (bool): 默认值为 `false`, 如果azure中不存在容器, `AzureBlobProvider` 将尝试创建它. |
|||
|
|||
## Azure BLOB 名称计算器 |
|||
|
|||
Azure BLOB提供程序组织BLOB名称并实现一些约定. 默认情况下BLOB的全名由以下规则确定: |
|||
|
|||
* 如果当前租户为 `null`(或容器禁用多租户 - 请参阅[BLOB存储文档](Blob-Storing.md) 了解如何禁用容器的多租户),则追加 `host` 字符串. |
|||
* 如果当前租户不为 `null`,则追加 `tenants/<tenant-id>` 字符串. |
|||
* 追加 BLOB 名称. |
|||
|
|||
## 其他服务 |
|||
|
|||
* `AzureBlobProvider` 是实现Azure BLOB存储提供程序的主要服务,如果你想要通过[依赖注入](Dependency-Injection.md)覆盖/替换它(不要替换 `IBlobProvider` 接口,而是替换 `AzureBlobProvider` 类). |
|||
* `IAzureBlobNameCalculator` 服务用于计算文件路径. 默认实现是 `DefaultAzureBlobNameCalculator` . 如果你想自定义文件路径计算,可以替换/覆盖它. |
|||
|
|||
@ -1 +1,177 @@ |
|||
TODO... |
|||
# BLOB 存储: 创建自定义提供程序 |
|||
|
|||
本文档通过一个示例说明如何为BLOB存储系统创建新的存储提供程序. |
|||
|
|||
> 阅读[BLOB存储文档](Blob-Storing.md)了解如何使用BLOB存储系统. 本文档仅介绍如何创建新存储提供程序. |
|||
|
|||
## 示例实现 |
|||
|
|||
第一步是创建一个实现 `IBlobProvider` 接口或 `BlobProviderBase` 抽象类继承的类. |
|||
|
|||
````csharp |
|||
using System.IO; |
|||
using System.Threading.Tasks; |
|||
using Volo.Abp.BlobStoring; |
|||
using Volo.Abp.DependencyInjection; |
|||
|
|||
namespace AbpDemo |
|||
{ |
|||
public class MyCustomBlobProvider : BlobProviderBase, ITransientDependency |
|||
{ |
|||
public override Task SaveAsync(BlobProviderSaveArgs args) |
|||
{ |
|||
//TODO... |
|||
} |
|||
|
|||
public override Task<bool> DeleteAsync(BlobProviderDeleteArgs args) |
|||
{ |
|||
//TODO... |
|||
} |
|||
|
|||
public override Task<bool> ExistsAsync(BlobProviderExistsArgs args) |
|||
{ |
|||
//TODO... |
|||
} |
|||
|
|||
public override Task<Stream> GetOrNullAsync(BlobProviderGetArgs args) |
|||
{ |
|||
//TODO... |
|||
} |
|||
} |
|||
} |
|||
```` |
|||
|
|||
* `MyCustomBlobProvider` 继承 `BlobProviderBase` 并覆盖 `abstract` 方法. 实际的实现取决于你. |
|||
* 实现 `ITransientDependency` 接口将这个类注做为瞬态服务注册到[依赖注入](Dependency-Injection.md)系统. |
|||
|
|||
> **注意: 命名约定很重要**. 如果类名没有以 `BlobProvider` 结尾,则必须手动注册/公开你的服务为 `IBlobProvider`. |
|||
|
|||
这是所有. 现在你可以配置容器(在[模块](Module-Development-Basics.md)的 `ConfigureServices` 方法中)使用 `MyCustomBlobProvider` 类: |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.ConfigureDefault(container => |
|||
{ |
|||
container.ProviderType = typeof(MyCustomBlobProvider); |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
> 如果你想配置特定的容器,请参阅[BLOB存储文档](Blob-Storing.md). |
|||
|
|||
### BlobContainerConfiguration 扩展方法 |
|||
|
|||
如果你想提供一个更简单的配置方式,可以为 `BlobContainerConfiguration` 类创建一个扩展方法: |
|||
|
|||
````csharp |
|||
public static class MyBlobContainerConfigurationExtensions |
|||
{ |
|||
public static BlobContainerConfiguration UseMyCustomBlobProvider( |
|||
this BlobContainerConfiguration containerConfiguration) |
|||
{ |
|||
containerConfiguration.ProviderType = typeof(MyCustomBlobProvider); |
|||
return containerConfiguration; |
|||
} |
|||
} |
|||
```` |
|||
|
|||
然后你可以使用扩展方法更容易地配置容器: |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.ConfigureDefault(container => |
|||
{ |
|||
container.UseMyCustomBlobProvider(); |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
### 额外的配置选项 |
|||
|
|||
`BlobContainerConfiguration` 允许添加/删除提供程序特定的配置对象. 如果你的提供者需要额外的配置,你可以为 `BlobContainerConfiguration` 创建一个包装类提供的类型安全配置选项: |
|||
|
|||
````csharp |
|||
public class MyCustomBlobProviderConfiguration |
|||
{ |
|||
public string MyOption1 |
|||
{ |
|||
get => _containerConfiguration |
|||
.GetConfiguration<string>("MyCustomBlobProvider.MyOption1"); |
|||
set => _containerConfiguration |
|||
.SetConfiguration("MyCustomBlobProvider.MyOption1", value); |
|||
} |
|||
|
|||
private readonly BlobContainerConfiguration _containerConfiguration; |
|||
|
|||
public MyCustomBlobProviderConfiguration( |
|||
BlobContainerConfiguration containerConfiguration) |
|||
{ |
|||
_containerConfiguration = containerConfiguration; |
|||
} |
|||
} |
|||
```` |
|||
|
|||
然后你可以这样更改 `MyBlobContainerConfigurationExtensions` 类: |
|||
|
|||
````csharp |
|||
public static class MyBlobContainerConfigurationExtensions |
|||
{ |
|||
public static BlobContainerConfiguration UseMyCustomBlobProvider( |
|||
this BlobContainerConfiguration containerConfiguration, |
|||
Action<MyCustomBlobProviderConfiguration> configureAction) |
|||
{ |
|||
containerConfiguration.ProviderType = typeof(MyCustomBlobProvider); |
|||
|
|||
configureAction.Invoke( |
|||
new MyCustomBlobProviderConfiguration(containerConfiguration) |
|||
); |
|||
|
|||
return containerConfiguration; |
|||
} |
|||
|
|||
public static MyCustomBlobProviderConfiguration GetMyCustomBlobProviderConfiguration( |
|||
this BlobContainerConfiguration containerConfiguration) |
|||
{ |
|||
return new MyCustomBlobProviderConfiguration(containerConfiguration); |
|||
} |
|||
} |
|||
```` |
|||
|
|||
* 向 `UseMyCustomBlobProvider` 方法添加了一个参数,允许开发人员设置其他选项. |
|||
* 添加了一个新的 `GetMyCustomBlobProviderConfiguration` 方法,该方法将在 `MyCustomBlobProvider` 类内使用获取配置的值. |
|||
|
|||
然后任何人都可以如下设置 `MyOption1`: |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.ConfigureDefault(container => |
|||
{ |
|||
container.UseMyCustomBlobProvider(provider => |
|||
{ |
|||
provider.MyOption1 = "my value"; |
|||
}); |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
最后你可以使用 `GetMyCustomBlobProviderConfiguration` 方法访问额外的选项: |
|||
|
|||
````csharp |
|||
public class MyCustomBlobProvider : BlobProviderBase, ITransientDependency |
|||
{ |
|||
public override Task SaveAsync(BlobProviderSaveArgs args) |
|||
{ |
|||
var config = args.Configuration.GetMyCustomBlobProviderConfiguration(); |
|||
var value = config.MyOption1; |
|||
|
|||
//... |
|||
} |
|||
} |
|||
```` |
|||
|
|||
## 贡献? |
|||
|
|||
如果你创建了一个新的提供程序,并且认为它对其他开发者有用,请考虑为GitHub上的ABP框架做出[贡献](Contribution/Index.md). |
|||
@ -0,0 +1,94 @@ |
|||
# BLOB存储数据库提供程序 |
|||
|
|||
BLOB存储数据库提供程序可以将BLOB存储在关系或非关系数据库中. |
|||
|
|||
有两个数据库提供程序实现; |
|||
|
|||
* [Volo.Abp.BlobStoring.Database.EntityFrameworkCore](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Database.EntityFrameworkCore) 包实现[EF Core](Entity-Framework-Core.md), 它可以通过EF Core存储BLOB在[任何支持的DBMS](https://docs.microsoft.com/en-us/ef/core/providers/)中. |
|||
* [Volo.Abp.BlobStoring.Database.MongoDB](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Database.MongoDB) 包实现了[MongoDB](MongoDB.md). |
|||
|
|||
> 阅读[BLOB存储文档](Blob-Storing.md)了解如何使用BLOB存储系统. 本文档仅介绍如何为容器配置数据库提供程序. |
|||
|
|||
## 安装 |
|||
|
|||
### 自动安装 |
|||
|
|||
如果你已基于[应用程序启动模板](Startup-Templates/Application.md)创建了解决方案,则可以使用 `abp add-module` [CLI](CLI.md)命令将相关软件包自动添加到解决方案中. |
|||
|
|||
在包含解决方案(`.sln`)文件的文件夹中打开命令行运行以下命令: |
|||
|
|||
````bash |
|||
abp add-module Volo.Abp.BlobStoring.Database |
|||
```` |
|||
|
|||
此命令将所有NuGet软件包添加到解决方案的相应层. 如果使用的是EF Core,它会添加必要的配置,添加新的数据库迁移并更新数据库. |
|||
|
|||
### 手动安装 |
|||
|
|||
这里是此提供程序定义的所有包: |
|||
|
|||
* [Volo.Abp.BlobStoring.Database.Domain.Shared](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Domain.Shared) |
|||
* [Volo.Abp.BlobStoring.Database.Domain](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Database.Domain) |
|||
* [Volo.Abp.BlobStoring.Database.EntityFrameworkCore](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Database.EntityFrameworkCore) |
|||
* [Volo.Abp.BlobStoring.Database.MongoDB](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Database.MongoDB) |
|||
|
|||
你可以只安装 `Volo.Abp.BlobStoring.Database.EntityFrameworkCore` 或 `Volo.Abp.BlobStoring.Database.MongoDB` (根据你的偏好),因为它们依赖其他包. |
|||
|
|||
安装完成后,添加 `DepenedsOn` 属性到相关[模块](Module-Development-Basics.md).下面是由上面列出的相关NuGet包定义的模块类列表: |
|||
|
|||
* `BlobStoringDatabaseDomainModule` |
|||
* `BlobStoringDatabaseDomainSharedModule` |
|||
* `BlobStoringDatabaseEntityFrameworkCoreModule` |
|||
* `BlobStoringDatabaseMongoDbModule` |
|||
|
|||
如果你正在使用EF Core,还需要配置你的**Migration DbContext**将BLOB存储表添加到你的数据库. 在 `OnModelCreating` 方法中调用 `builder.ConfigureBlobStoring()` 扩展方法来包含到DbContext的映射. 你可以使用标准的 `Add-Migration` 和 `Update-Database` [命令](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/)在数据库中创建必要的表. |
|||
|
|||
## 配置 |
|||
|
|||
### 连接字符串 |
|||
|
|||
如果你要使用你的 `Default` 连接字符串,则不需要做任何其他配置. |
|||
|
|||
如果要将BLOB存储到单独的数据库,请在配置文件(`appsettings.json`)中将 `AbpBlobStoring` 用作连接字符串名称. 请阅读[EF Core Migrations](Entity-Framework-Core-Migrations.md)文档了解如何为所需模块创建和使用其他数据库. |
|||
|
|||
### 配置容器 |
|||
|
|||
如同[BLOB存储文档](Blob-Storing.md)所述,配置是在[模块](Module-Development-Basics.md)类的 `ConfigureServices` 方法完成的. |
|||
|
|||
**示例: 配置为默认使用数据库系统存储提供程序** |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.ConfigureDefault(container => |
|||
{ |
|||
container.UseDatabase(); |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
> 参阅[BLOB存储文档](Blob-Storing.md) 学习如何为指定容器配置提供程序. |
|||
|
|||
## 附加信息 |
|||
|
|||
它需要使用[BLOB存储服务](Blob-Storing.md)来使用BLOB存储系统. 但是如果要处理数据库表/实体,可以使用以下信息. |
|||
|
|||
### 实体 |
|||
|
|||
此模块定义的实体: |
|||
|
|||
* `DatabaseBlobContainer` (aggregate root) 表示存储在数据库中的容器. |
|||
* `DatabaseBlob` (aggregate root) 表示数据库中的BLOB. |
|||
|
|||
参阅[实体文档](Entities.md)了解什么是实体和聚合根. |
|||
|
|||
### 仓储 |
|||
|
|||
* `IDatabaseBlobContainerRepository` |
|||
* `IDatabaseBlobRepository` |
|||
|
|||
你还可以使用 `IRepository` 和 `IRepository` 来获得 `IQueryable` 能力. 更多信息请参阅[仓储文档](Repositories.md). |
|||
|
|||
### 其他服务 |
|||
|
|||
* `DatabaseBlobProvider` 是实现数据库BLOB存储提供程序的主要服务,如果你想要通过[依赖注入](Dependency-Injection.md)覆盖/替换它(不要替换 `IBlobProvider` 接口,而是替换 `DatabaseBlobProvider` 类). |
|||
@ -1 +1,58 @@ |
|||
TODO... |
|||
# BLOB存储文件系统提供程序 |
|||
|
|||
文件系统存储提供程序用于将BLOB作为文件夹中的标准文件存储在本地文件系统中. |
|||
|
|||
> 阅读[BLOB存储文档](Blob-Storing.md)了解如何使用BLOB存储系统. 本文档仅介绍如何为容器配置文件系统. |
|||
|
|||
## 介绍 |
|||
|
|||
使用ABP CLI添加[Volo.Abp.BlobStoring.FileSystem](https://www.nuget.org/packages/Volo.Abp.BlobStoring.FileSystem)NuGet包到你的项目: |
|||
|
|||
* 安装 [ABP CLI](https://docs.abp.io/en/abp/latest/CLI), 如果你还没有安装. |
|||
* 在要添加 `Volo.Abp.BlobStoring.FileSystem` 包的 `.csproj` 文件目录打开命令行. |
|||
* 运行 `abp add-package Volo.Abp.BlobStoring.FileSystem` 命令. |
|||
|
|||
如果要手动安装,在你的项目中安装 `Volo.Abp.BlobStoring.FileSystem` NuGet包然后将`[DependsOn(typeof(AbpBlobStoringFileSystemModule))]`添加到项目内的[ABP模块](Module-Development-Basics.md)类中. |
|||
|
|||
## 配置 |
|||
|
|||
如同[BLOB存储文档](Blob-Storing.md)所述,配置是在[模块](Module-Development-Basics.md)类的 `ConfigureServices` 方法完成的. |
|||
|
|||
**示例: 配置为默认使用文件系统存储提供程序** |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.ConfigureDefault(container => |
|||
{ |
|||
container.UseFileSystem(fileSystem => |
|||
{ |
|||
fileSystem.BasePath = "C:\\my-files"; |
|||
}); |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
`UseFileSystem` 扩展方法用于为容器设置文件系统提供程序并配置文件系统选项. |
|||
|
|||
> 参阅[BLOB存储文档](Blob-Storing.md) 学习如何为指定容器配置提供程序. |
|||
|
|||
### 选项 |
|||
|
|||
* **BasePath** (string): 存储BLOB的基本文件夹路径,它是必选的. |
|||
* **AppendContainerNameToBasePath** (bool; 默认: `true`): 指定是否在基本文件夹中创建具有容器名称的文件夹. 如果你在同一个 `BaseFolder` 中存储多个容器,请将其保留为`true`. 如果你不喜欢不必要的更深层次的文件夹,你可以将它设置为 `false`. |
|||
|
|||
## 文件路径计算 |
|||
|
|||
文件系统提供程序在文件夹中组织BLOB文件并实现一些约定. 默认情况下,BLOB文件的完整路径由以下规则确定: |
|||
|
|||
* 它以如上所述配置的 `BasePath` 开始. |
|||
* 如果当前租户为 `null`(或容器禁用多租户 - 请参阅[BLOB存储文档](Blob-Storing.md) 了解如何禁用容器的多租户),则追加 `host` 文件夹. |
|||
* 如果当前租户不为 `null`,则追加 `tenants/<tenant-id>` 文件夹. |
|||
* 如果 `AppendContainerNameToBasePath` 为`true`,则追加容器的名称. 如果容器名称包含 `/`,将导致文件夹嵌套. |
|||
* 追加BLOB名称,如果BLOB名称包含 `/` 它创建文件夹. 如果BLOB名称包含 `.` 它将有一个文件扩展名. |
|||
|
|||
## 扩展文件系统提供程序 |
|||
|
|||
* `FileSystemBlobProvider` 是实现文件系统存储的主要服务. 你可以从这个类继承并[覆盖](Customizing-Application-Modules-Overriding-Services.md)方法进行自定义. |
|||
* `IBlobFilePathCalculator` 服务用于计算文件路径. 默认实现是 `DefaultBlobFilePathCalculator` . 如果你想自定义文件路径计算,可以替换/覆盖它. |
|||
@ -1 +1,306 @@ |
|||
TODO... |
|||
# BLOB 存储 |
|||
|
|||
通常将文件内容存储在应用程序中并根据需要读取这些文件内容. 不仅是文件你可能还需要将各种类型的[BLOB](https://en.wikipedia.org/wiki/Binary_large_object)(大型二进制对象)保存到存储中. 例如你可能要保存用户个人资料图片. |
|||
|
|||
BLOB通常是一个**字节数组**. 有很多地方可以存储BLOB项. 可以选择将其存储在本地文件系统中,共享数据库中或[Azure BLOB存储](https://azure.microsoft.com/zh-cn/services/storage/blobs/)中. |
|||
|
|||
ABP框架为BLOB提供了抽象,并提供了一些可以轻松集成到的预构建存储提供程序. 抽象有一些好处; |
|||
|
|||
* 你可以通过几行配置**轻松的集成**你喜欢的BLOB存储提供程序. |
|||
* 你可以**轻松的更改**BLOB存储,而不用改变你的应用程序代码. |
|||
* 如果你想创建**可重用的应用程序模块**,无需假设BLOB的存储方式. |
|||
|
|||
ABP BLOG存储系统兼容ABP框架其他功能,如[多租户](Multi-Tenancy.md). |
|||
|
|||
## BLOB 存储提供程序 |
|||
|
|||
ABP框架已经有以下存储提供程序的实现; |
|||
|
|||
* [File System](Blob-Storing-File-System.md):将BLOB作为标准文件存储在本地文件系统的文件夹中. |
|||
* [Database](Blob-Storing-Database.md): 将BLOB存储在数据库中. |
|||
* [Azure](Blob-Storing-Azure.md): 将BLOG存储在 [Azure BLOB storage](https://azure.microsoft.com/en-us/services/storage/blobs/)中. |
|||
|
|||
以后会实现更多的提供程序,你可以为自己喜欢的提供程序创建[请求](https://github.com/abpframework/abp/issues/new),或者你也可以[自己实现](Blob-Storing-Custom-Provider.md)它并[贡献](Contribution/Index.md)到ABP框架. |
|||
|
|||
可以在**容器系统**的帮助下一起**使用多个提供程序**,其中每个容器可以使用不同的提供程序. |
|||
|
|||
> 除非你**配置存储提供程序**否则BLOB存储系统无法工作. 有关存储提供程序配置请参考链接的文档. |
|||
|
|||
## 安装 |
|||
|
|||
[Volo.Abp.BlobStoring](https://www.nuget.org/packages/Volo.Abp.BlobStoring)是定义BLOB存储服务的主要包. 你可以用此包使用BLOB存储系统而不依赖特定存储提供程序. |
|||
|
|||
使用ABP CLI这个包添加到你的项目: |
|||
|
|||
* 安装 [ABP CLI](https://docs.abp.io/en/abp/latest/CLI), 如果你还没有安装. |
|||
* 在要添加 `Volo.Abp.BlobStoring` 包的 `.csproj` 文件目录打开命令行. |
|||
* 运行 `abp add-package Volo.Abp.BlobStoring` 命令. |
|||
|
|||
如果要手动安装,在你的项目中安装 `Volo.Abp.BlobStoring` NuGet包然后将`[DependsOn(typeof(AbpBlobStoringModule))]`添加到项目内的[ABP模块](Module-Development-Basics.md)类中. |
|||
|
|||
## IBlobContainer |
|||
|
|||
`IBlobContainer` 是存储和读取BLOB的主要接口. 应用程序可能有多个容器,每个容器都可以单独配置. 有一个**默认容器**可以通过注入 `IBlobContainer` 来简单使用. |
|||
|
|||
**示例: 简单地保存和读取命名BLOB的字节** |
|||
|
|||
````csharp |
|||
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"); |
|||
} |
|||
} |
|||
} |
|||
```` |
|||
|
|||
该服务用 `my-blob-1` 名称保存给定的字节,然后以相同的名称获取先前保存的字节. |
|||
|
|||
> 一个BLOB是一个命名对象,**每个BLOB都应该有一个唯一的名称**,它是一个任意的字符串. |
|||
|
|||
`IBlobContainer` 可以处理 `Stream` 和 `byte[]` 对象,在下一节中将详细介绍. |
|||
|
|||
### 保存 BLOB |
|||
|
|||
`SaveAsync` 方法用于保存新的或替换现有的BLOB. 默认情况下,它可以保存 `Stream`,但是有一个快捷的扩展方法来保存字节数组. |
|||
|
|||
`SaveAsync` 有以下参数: |
|||
|
|||
* **name** (string): 唯一的BLOB名称. |
|||
* **stream** (Stream) or **byte** (byte[]): 读取BLOB内容或字节数组的流. |
|||
* **overrideExisting** (bool): 设置为 `true`,如果BLOB内容已经存在,则替换它. 默认值为 `false`,则抛出 `BlobAlreadyExistsException` 异常. |
|||
|
|||
### 读取/获取 BLOB |
|||
|
|||
* `GetAsync`: 返回给定BLOB名称可用于读取BLOB内容的 `Stream` 对象. 使用后始终要**dispose流**. 如果找不到具有给定名称的BLOB,则抛出异常. |
|||
* `GetOrNullAsync`: 与 `GetAsync` 方法相反,如果未找到给定名称的BLOG,则返回 `null`. |
|||
* `GetAllBytesAsync`: 返回 `byte[]` 而不是 `Stream`. 如果找不到具有给定名称的BLOB,则抛出异常. |
|||
* `GetAllBytesOrNullAsync`: 与 `GetAllBytesAsync` 方法相反,如果未找到给定名称的BLOG,则返回 `null`. |
|||
|
|||
### 删除 BLOB |
|||
|
|||
`DeleteAsync` 使用给定BLOB名称删除BLOB数据. 如果找不到给定的BLOB不会引发任何异常. 相反如果你关心BLOB,它会返回一个 `bool`,表示BLOB实际上是否已删除. |
|||
|
|||
### 其他方法 |
|||
|
|||
* `ExistsAsync` 方法简单的检查容器中是否存在具有给定名称的BLOB. |
|||
|
|||
### 关于命名BLOB |
|||
|
|||
没有命名BLOB的规则. BLOB名称只是每个容器(和每个租户-参见"*多租户*"部分)唯一的字符串. 但是不同的存储提供程序可能会按惯例实施某些做法. 例如[文件系统提供程序](Blob-Storing-File-System.md)在BLOB名称中使用目录分隔符 (`/`) 和文件扩展名(如果BLOB名称为 `images/common/x.png` ,则在根容器文件夹下的 `images/common` 文件夹中存储 `x.png`). |
|||
|
|||
## 类型化 IBlobContainer |
|||
|
|||
类型化BLOB容器系统是一种在应用程序中创建和管理**多个容器**的方法; |
|||
|
|||
* **每个容器分别存储**. 这意味着BLOB名称在一个容器中应该是唯一的,两个具有相同名称的BLOB可以存在不同的容器中不会互相影响. |
|||
* **每个容器可以单独配置**,因此每个容器可以根据你的配置使用不同的存储提供程序. |
|||
|
|||
要创建类型化容器,需要创建一个简单的用 `BlobContainerName` 属性装饰的类: |
|||
|
|||
````csharp |
|||
using Volo.Abp.BlobStoring; |
|||
|
|||
namespace AbpDemo |
|||
{ |
|||
[BlobContainerName("profile-pictures")] |
|||
public class ProfilePictureContainer |
|||
{ |
|||
|
|||
} |
|||
} |
|||
```` |
|||
|
|||
> 如果不使用 `BlobContainerName` attribute,ABP Framework将使用类的全名(带有名称空间),但是始终建议使用稳定的容器名称,即使重命名该类也不会被更改. |
|||
|
|||
创建容器类后,可以为容器类型注入 `IBlobContainer<T>`. |
|||
|
|||
**示例: 用于保存和读取[当前用户](CurrentUser.md)的个人资料图片的[应用服务](Application-Services.md)** |
|||
|
|||
````csharp |
|||
[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>` 有与 `IBlobContainer` 相同的方法. |
|||
|
|||
> 在开发可重复使用的模块时,**始终使用类型化的容器是一个好习惯**,这样最终的应用程序就可以为你的容器配置提供程序,而不会影响其他容器. |
|||
|
|||
### 默认容器 |
|||
|
|||
如果不使用泛型参数,直接注入 `IBlobContainer` (如上所述),会得到默认容器. 注入默认容器的另一种方法是使用 `IBlobContainer<DefaultContainer>`,它返回完全相同的容器. |
|||
|
|||
默认容器的名称是 `Default`. |
|||
|
|||
### 命令容器 |
|||
|
|||
类型容器只是命名容器的快捷方式. 你可以注入并使用 `IBlobContainerFactory` 来获得一个BLOB容器的名称: |
|||
|
|||
````csharp |
|||
public class ProfileAppService : ApplicationService |
|||
{ |
|||
private readonly IBlobContainer _blobContainer; |
|||
|
|||
public ProfileAppService(IBlobContainerFactory blobContainerFactory) |
|||
{ |
|||
_blobContainer = blobContainerFactory.Create("profile-pictures"); |
|||
} |
|||
|
|||
//... |
|||
} |
|||
```` |
|||
|
|||
## IBlobContainerFactory |
|||
|
|||
`IBlobContainerFactory` 是用于创建BLOB容器的服务. 上面提供了一个示例. |
|||
|
|||
**示例: 通过名称创建容器** |
|||
|
|||
````csharp |
|||
var blobContainer = blobContainerFactory.Create("profile-pictures"); |
|||
```` |
|||
|
|||
**示例: 通过类型创建容器** |
|||
|
|||
````csharp |
|||
var blobContainer = blobContainerFactory.Create<ProfilePictureContainer>(); |
|||
```` |
|||
|
|||
> 通常你不需要使用 `IBlobContainerFactory`, 因为在注入 `IBlobContainer` 或`IBlobContainer<T>` 时会在内部使用它. |
|||
|
|||
## 配置容器 |
|||
|
|||
在使用容器之前应先对其进行配置. 最基本的配置是选择一个 **BLOB存储提供程序**(请参阅上面的"*BLOB存储提供程序*"部分). |
|||
|
|||
`AbpBlobStoringOptions` 是用于配置容器的[选项类](Options.md). 你可以在[模块](Module-Development-Basics.md)的 `ConfigureServices` 方法中配置选项. |
|||
|
|||
### 配置单个容器 |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.Configure<ProfilePictureContainer>(container => |
|||
{ |
|||
//TODO... |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
这个例子配置 `ProfilePictureContainer`. 你还可以通过容器名称进行配置: |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.Configure("profile-pictures", container => |
|||
{ |
|||
//TODO... |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
### 配置默认容器 |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.ConfigureDefault(container => |
|||
{ |
|||
//TODO... |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
> 默认容器有一个特殊情况;如果不为容器指定配置,则**返回到默认容器配置**. 这是一种为所有容器配置默认值并在需要时专门针对特定容器进行配置的好方法. |
|||
|
|||
### 配置所有容器 |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.ConfigureAll((containerName, containerConfiguration) => |
|||
{ |
|||
//TODO... |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
这是配置所有容器的方式. |
|||
|
|||
> 与配置默认容器的主要区别在于, `ConfigureAll` 会覆盖配置,即使它是专门为特定容器配置的. |
|||
|
|||
## 多租户 |
|||
|
|||
|
|||
如果你的应用程序是多租户的,BLOB存储系统可以**与[多租户](Multi-Tenancy.md)无缝协作**. 所有提供程序都将多租户实现为标准功能. 它们将不同租户的**BLOB彼此隔离**,因此它们只能访问自己的BLOB. 这意味着你可以**为不同的租户使用相同的BLOB名称**. |
|||
|
|||
如果应用程序是多租户的,则可能需要单独控制容器的**多租户行为**. 例如你可能希望**禁用特定容器的多租户**,这样容器中的BLOB将对**所有租户可用**. 这是在所有租户之间共享BLOB的一种方法. |
|||
|
|||
**示例: 禁用特定容器的多租户** |
|||
|
|||
````csharp |
|||
Configure<AbpBlobStoringOptions>(options => |
|||
{ |
|||
options.Containers.Configure<ProfilePictureContainer>(container => |
|||
{ |
|||
container.IsMultiTenant = false; |
|||
}); |
|||
}); |
|||
```` |
|||
|
|||
> 如果你的应用程序不是多租户的,不用担心,它会正常工作. 你不需要配置 `IsMultiTenant` 选项. |
|||
|
|||
## 扩展BLOB存储系统 |
|||
|
|||
大多数时候除了创建定制的BLOB存储提供程序外,你不需要[自定义BLOB存储系统](Blob-Storing-Custom-Provider.md).但是如果需要,你可以替换任何服务(通过[依赖注入](Dependency-Injection.md)). 这里有一些上面没有提到的其他服务,但你可能想知道: |
|||
|
|||
* `IBlobProviderSelector` 用于通过容器名称获取 `IBlobProvider` 实例. 默认实现(`DefaultBlobProviderSelector`)使用配置选择提供程序. |
|||
* `IBlobContainerConfigurationProvider` 用于获取给定容器名称的`BlobContainerConfiguration`. 默认实现(`DefaultBlobContainerConfigurationProvider`)从上述 `AbpBlobStoringOptions` 获取配置. |
|||
|
|||
## BLOB 存储 vs 文件管理系统 |
|||
|
|||
注意BLOB存储不是一个文件管理系统. 它是一个用于保存,获取和删除命名BLOG的低级别系统. 它不提供目录那样的层次结构,这是典型文件系统所期望的. |
|||
|
|||
如果你想创建文件夹并在文件夹之间移动文件,为文件分配权限并在用户之间共享文件,那么你需要在BLOB存储系统上实现你自己的应用程序. |
|||
|
|||
## 另请参阅 |
|||
|
|||
* [创建自定义BLOB存储提供程序](Blob-Storing-Custom-Provider.md) |
|||
Loading…
Reference in new issue