Add Volo.Abp.BlobStoring.Aliyun

docs/en/Blob-Storing-Aliyun.md

@@ -0,0 +1,73 @@
+# BLOB Storing Aliyun Provider
+
+BLOB Storing Aliyun Provider can store BLOBs in [Aliyun Blob storage](https://help.aliyun.com/product/31815.html).
+
+> Read the [BLOB Storing document](Blob-Storing.md) to understand how to use the BLOB storing system. This document only covers how to configure containers to use a Aliyun BLOB as the storage provider.
+
+## Installation
+
+Use the ABP CLI to add [Volo.Abp.BlobStoring.Aliyun](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Aliyun) NuGet package to your project:
+
+* Install the [ABP CLI](https://docs.abp.io/en/abp/latest/CLI) if you haven't installed before.
+* Open a command line (terminal) in the directory of the `.csproj` file you want to add the `Volo.Abp.BlobStoring.Aliyun` package.
+* Run `abp add-package Volo.Abp.BlobStoring.Aliyun` command.
+
+If you want to do it manually, install the [Volo.Abp.BlobStoring.Aliyun](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Aliyun) NuGet package to your project and add `[DependsOn(typeof(AbpBlobStoringAliyunModule))]` to the [ABP module](Module-Development-Basics.md) class inside your project.
+
+## Configuration
+
+Configuration is done in the `ConfigureServices` method of your [module](Module-Development-Basics.md) class, as explained in the [BLOB Storing document](Blob-Storing.md).
+
+**Example: Configure to use the Aliyun storage provider by default**
+
+````csharp
+Configure<AbpBlobStoringOptions>(options =>
+{
+    options.Containerscontainer.UseAliyun(aliyun =>
+    {
+        aliyun.AccessKeyId = "your aliyun access key id";
+        aliyun.AccessKeySecret = "your aliyun access key secret";
+        aliyun.Endpoint = "your oss endpoint";
+        aliyun.RegionId = "your sts region id";
+        aliyun.RoleArn = "the arn of ram role";
+        aliyun.RoleSessionName = "the name of the certificate";
+        aliyun.Policy = "policy";
+        aliyun.DurationSeconds = "expiration date";
+        aliyun.ContainerName = "your aliyun container name";
+        aliyun.CreateContainerIfNotExists = false;
+    });
+});
+````
+
+> See the [BLOB Storing document](Blob-Storing.md) to learn how to configure this provider for a specific container.
+
+### Options
+
+* **AccessKeyId** ([NotNull]string): AccessKey is the key to access the Alibaba Cloud API. It has full permissions for the account. Please keep it safe! Recommend to follow [Alibaba Cloud security best practicess](https://help.aliyun.com/document_detail/102600.html),Use RAM sub-user AccessKey to call API.
+* **AccessKeySecret** ([NotNull]string): Same as above.
+* **Endpoint** ([NotNull]string): Endpoint is the external domain name of OSS. See the [document](https://help.aliyun.com/document_detail/31837.html) for details.
+* **RegionId** (string): Access address of STS service. See the [document](https://help.aliyun.com/document_detail/66053.html) for details.
+* **RoleArn** ([NotNull]string): STS required role ARN. See the [document](https://help.aliyun.com/document_detail/100624.html) for details.
+* **RoleSessionName** ([NotNull]string): Used to identify the temporary access credentials, it is recommended to use different application users to distinguish.
+* **Policy** (string): Additional permission restrictions. See the [document](https://help.aliyun.com/document_detail/100680.html) for details.
+* **DurationSeconds** (int): Validity period(s) of a temporary access certificate,minimum is 900 and the maximum is 3600. **note**: Using subaccounts operated OSS,if the value is 0.
+* **ContainerName** (string): You can specify the container name in Aliyun. If this is not specified, it uses the name of the BLOB container defined with the `BlogContainerName` attribute (see the [BLOB storing document](Blob-Storing.md)). Please note that Aliyun has some **rules for naming containers**. A container name must be a valid DNS name, conforming to the [following naming rules](https://help.aliyun.com/knowledge_detail/39668.html):
+    * Container names must start or end with a letter or number, and can contain only letters, numbers, and the dash (-) character.
+    * Container names Must start and end with lowercase letters and numbers.
+    * Container names must be from **3** through **63** characters long.
+* **CreateContainerIfNotExists** (bool): Default value is `false`, If a container does not exist in Aliyun, `AliyunBlobProvider` will try to create it.
+
+
+## Aliyun Blob Name Calculator
+
+Aliyun Blob Provider organizes BLOB name and implements some conventions. The full name of a BLOB is determined by the following rules by default:
+
+* Appends `host` string if [current tenant](Multi-Tenancy.md) is `null` (or multi-tenancy is disabled for the container - see the [BLOB Storing document](Blob-Storing.md) to learn how to disable multi-tenancy for a container).
+* Appends `tenants/<tenant-id>` string if current tenant is not `null`.
+* Appends the BLOB name.
+
+## Other Services
+
+* `AliyunBlobProvider` is the main service that implements the Aliyun BLOB storage provider, if you want to override/replace it via [dependency injection](Dependency-Injection.md) (don't replace `IBlobProvider` interface, but replace `AliyunBlobProvider` class).
+* `IAliyunBlobNameCalculator` is used to calculate the full BLOB name (that is explained above). It is implemented by the `DefaultAliyunBlobNameCalculator` by default.
+* `IOssClientFactory` is used create OSS client. It is implemented by the `DefaultOssClientFactory` by default. You can override/replace it,if you want customize.

docs/en/docs-nav.json

@@ -216,6 +216,10 @@
                   "text": "Azure Provider",
                   "path": "Blob-Storing-Azure.md"
                 },
+                {
+                  "text": "Aliyun Provider",
+                  "path": "Blob-Storing-Aliyun.md"
+                },
                 {
                   "text": "Create a Custom Provider",
                   "path": "Blob-Storing-Custom-Provider.md"

docs/zh-Hans/Blob-Storing-Aliyun.md

@@ -0,0 +1,72 @@
+# BLOB Storing Aliyun提供程序
+
+BLOB存储Aliyun提供程序可以将BLOB存储在[Aliyun Blob storage](https://help.aliyun.com/product/31815.html)中.
+
+> 阅读[BLOB存储文档](Blob-Storing.md)了解如何使用BLOB存储系统. 本文档仅介绍如何为容器配置Aliyun提供程序.
+
+## 安装
+
+使用ABP CLI添加[Volo.Abp.BlobStoring.Aliyun](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Aliyun)NuGet包到你的项目:
+
+* 安装 [ABP CLI](https://docs.abp.io/en/abp/latest/CLI), 如果你还没有安装.
+* 在要添加 `Volo.Abp.BlobStoring.Aliyun` 包的 `.csproj` 文件目录打开命令行.
+* 运行 `Volo.Abp.BlobStoring.Aliyun` 命令.
+
+如果要手动安装,在你的项目中安装 `Volo.Abp.BlobStoring.Aliyun` NuGet包然后将`[DependsOn(typeof(AbpBlobStoringAliyunModule))]`添加到项目内的[ABP模块](Module-Development-Basics.md)类中.
+
+## 配置
+
+如同[BLOB存储文档](Blob-Storing.md)所述,配置是在[模块](Module-Development-Basics.md)类的 `ConfigureServices` 方法完成的.
+
+**示例: 配置为默认使用Aliyun存储提供程序**
+
+````csharp
+Configure<AbpBlobStoringOptions>(options =>
+{
+    options.Containerscontainer.UseAliyun(aliyun =>
+    {
+        aliyun.AccessKeyId = "your aliyun access key id";
+        aliyun.AccessKeySecret = "your aliyun access key secret";
+        aliyun.Endpoint = "your oss endpoint";
+        aliyun.RegionId = "your sts region id";
+        aliyun.RoleArn = "the arn of ram role";
+        aliyun.RoleSessionName = "the name of the certificate";
+        aliyun.Policy = "policy";
+        aliyun.DurationSeconds = "expiration date";
+        aliyun.ContainerName = "your aliyun container name";
+        aliyun.CreateContainerIfNotExists = false;
+    });
+});
+````
+
+> 参阅[BLOB存储文档](Blob-Storing.md) 学习如何为指定容器配置提供程序.
+
+### 选项
+
+* **AccessKeyId** ([NotNull]string): 云账号AccessKey是访问阿里云API的密钥,具有该账户完全的权限,请你务必妥善保管!强烈建议遵循[阿里云安全最佳实践](https://help.aliyun.com/document_detail/102600.html),使用RAM子用户AccessKey来进行API调用.
+* **AccessKeySecret** ([NotNull]string): 同上.
+* **Endpoint** ([NotNull]string): Endpoint表示OSS对外服务的访问域名. [访问域名和数据中心](https://help.aliyun.com/document_detail/31837.html)
+* **RegionId** (string): STS服务的接入地址,每个地址的功能都相同,请尽量在同地域进行调用. [接入地址](https://help.aliyun.com/document_detail/66053.html)
+* **RoleArn** ([NotNull]string): STS所需角色ARN. [STS临时授权访问OSS](https://help.aliyun.com/document_detail/100624.html)
+* **RoleSessionName** ([NotNull]string): 用来标识临时访问凭证的名称,建议使用不同的应用程序用户来区分.
+* **Policy** (string): 在扮演角色的时候额外添加的权限限制. 请参见[基于RAM Policy的权限控制](https://help.aliyun.com/document_detail/100680.html).
+* **DurationSeconds** (int): 设置临时访问凭证的有效期,单位是s,最小为900,最大为3600. **注**:为0则使用子账号操作OSS.
+* **ContainerName** (string): 你可以在aliyun中指定容器名称. 如果没有指定它将使用 `BlogContainerName` 属性定义的BLOB容器的名称(请参阅[BLOB存储文档](Blob-Storing.md)). 请注意Aliyun有一些**命名容器的规则**,容器名称必须是有效的DNS名称,[符合以下命名规则](https://help.aliyun.com/knowledge_detail/39668.html):
+    * 只能包含小写字母,数字和短横线(-)
+    * 必须以小写字母和数字开头和结尾
+    * Bucket名称的长度限制在**3**到**63**个字符之间
+* **CreateContainerIfNotExists** (bool): 默认值为 `false`, 如果aliyun中不存在容器, `AliyunBlobProvider` 将尝试创建它.
+
+## Aliyun BLOB 名称计算器
+
+Aliyun BLOB提供程序组织BLOB名称并实现一些约定. 默认情况下BLOB的全名由以下规则确定:
+
+* 如果当前租户为 `null`(或容器禁用多租户 - 请参阅[BLOB存储文档](Blob-Storing.md) 了解如何禁用容器的多租户),则追加 `host` 字符串.
+* 如果当前租户不为 `null`,则追加 `tenants/<tenant-id>` 字符串.
+* 追加 BLOB 名称.
+
+## 其他服务
+
+* `AliyunBlobProvider` 是实现Aliyun BLOB存储提供程序的主要服务,如果你想要通过[依赖注入](Dependency-Injection.md)覆盖/替换它(不要替换 `IBlobProvider` 接口,而是替换 `AliyunBlobProvider` 类).
+* `IAliyunBlobNameCalculator` 服务用于计算文件路径. 默认实现是 `DefaultAliyunBlobNameCalculator`. 如果你想自定义文件路径计算,可以替换/覆盖它.
+* `IOssClientFactory` 服务用于生成OSS客户端. 默认实现是 `DefaultOssClientFactory` . 如果你想自定义OSS客户端生成,可以替换/覆盖它.

docs/zh-Hans/docs-nav.json

@@ -210,6 +210,10 @@
                   "text": "Azure提供程序",
                   "path": "Blob-Storing-Azure.md"
                 },
+                {
+                  "text": "Aliyun提供程序",
+                  "path": "Blob-Storing-Aliyun.md"
+                },
                 {
                   "text": "创建自定义提供程序",
                   "path": "Blob-Storing-Custom-Provider.md"

framework/Volo.Abp.sln

@@ -315,6 +315,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Volo.Abp.Caching.StackExcha
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Volo.Abp.Caching.StackExchangeRedis.Tests", "test\Volo.Abp.Caching.StackExchangeRedis.Tests\Volo.Abp.Caching.StackExchangeRedis.Tests.csproj", "{60D0E384-965E-4F81-9D71-B28F419254FC}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Volo.Abp.BlobStoring.Aliyun", "src\Volo.Abp.BlobStoring.Aliyun\Volo.Abp.BlobStoring.Aliyun.csproj", "{845E6A13-D1B5-4DDC-A16C-68D807E3B4C7}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Volo.Abp.BlobStoring.Aliyun.Tests", "test\Volo.Abp.BlobStoring.Aliyun.Tests\Volo.Abp.BlobStoring.Aliyun.Tests.csproj", "{8E49687A-E69F-49F2-8DB0-428D0883A937}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -937,6 +941,14 @@ Global
 		{60D0E384-965E-4F81-9D71-B28F419254FC}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{60D0E384-965E-4F81-9D71-B28F419254FC}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{60D0E384-965E-4F81-9D71-B28F419254FC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{845E6A13-D1B5-4DDC-A16C-68D807E3B4C7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{845E6A13-D1B5-4DDC-A16C-68D807E3B4C7}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{845E6A13-D1B5-4DDC-A16C-68D807E3B4C7}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{845E6A13-D1B5-4DDC-A16C-68D807E3B4C7}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8E49687A-E69F-49F2-8DB0-428D0883A937}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8E49687A-E69F-49F2-8DB0-428D0883A937}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8E49687A-E69F-49F2-8DB0-428D0883A937}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8E49687A-E69F-49F2-8DB0-428D0883A937}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -1096,6 +1108,8 @@ Global
 		{1738845A-5348-4EB8-B736-CD1D22A808B4} = {5DF0E140-0513-4D0D-BE2E-3D4D85CD70E6}
 		{2B83DF1F-0FD2-4DEA-ABC5-E324B51401D4} = {5DF0E140-0513-4D0D-BE2E-3D4D85CD70E6}
 		{60D0E384-965E-4F81-9D71-B28F419254FC} = {447C8A77-E5F0-4538-8687-7383196D04EA}
+		{845E6A13-D1B5-4DDC-A16C-68D807E3B4C7} = {5DF0E140-0513-4D0D-BE2E-3D4D85CD70E6}
+		{8E49687A-E69F-49F2-8DB0-428D0883A937} = {447C8A77-E5F0-4538-8687-7383196D04EA}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {BB97ECF4-9A84-433F-A80B-2A3285BDD1D5}

framework/src/Volo.Abp.BlobStoring.Aliyun/FodyWeavers.xml

@@ -0,0 +1,3 @@
+<Weavers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FodyWeavers.xsd">
+  <ConfigureAwait ContinueOnCapturedContext="false" />
+</Weavers>

framework/src/Volo.Abp.BlobStoring.Aliyun/FodyWeavers.xsd

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <!-- This file was generated by Fody. Manual changes to this file will be lost when your project is rebuilt. -->
+  <xs:element name="Weavers">
+    <xs:complexType>
+      <xs:all>
+        <xs:element name="ConfigureAwait" minOccurs="0" maxOccurs="1">
+          <xs:complexType>
+            <xs:attribute name="ContinueOnCapturedContext" type="xs:boolean" />
+          </xs:complexType>
+        </xs:element>
+      </xs:all>
+      <xs:attribute name="VerifyAssembly" type="xs:boolean">
+        <xs:annotation>
+          <xs:documentation>'true' to run assembly verification (PEVerify) on the target assembly after all weavers have been executed.</xs:documentation>
+        </xs:annotation>
+      </xs:attribute>
+      <xs:attribute name="VerifyIgnoreCodes" type="xs:string">
+        <xs:annotation>
+          <xs:documentation>A comma-separated list of error codes that can be safely ignored in assembly verification.</xs:documentation>
+        </xs:annotation>
+      </xs:attribute>
+      <xs:attribute name="GenerateXsd" type="xs:boolean">
+        <xs:annotation>
+          <xs:documentation>'false' to turn off automatic generation of the XML Schema file.</xs:documentation>
+        </xs:annotation>
+      </xs:attribute>
+    </xs:complexType>
+  </xs:element>
+</xs:schema>

framework/src/Volo.Abp.BlobStoring.Aliyun/Volo.Abp.BlobStoring.Aliyun.csproj

@@ -0,0 +1,27 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <Import Project="..\..\..\configureawait.props" />
+  <Import Project="..\..\..\common.props" />
+
+  <PropertyGroup>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <AssemblyName>Volo.Abp.BlobStoring.Aliyun</AssemblyName>
+    <PackageId>Volo.Abp.BlobStoring.Aliyun</PackageId>
+    <AssetTargetFallback>$(AssetTargetFallback);portable-net45+win8+wp8+wpa81;</AssetTargetFallback>
+    <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
+    <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
+    <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
+    <RootNamespace />
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="aliyun-net-sdk-sts" Version="3.0.4" />
+    <PackageReference Include="Aliyun.OSS.SDK.NetCore" Version="2.10.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Volo.Abp.BlobStoring\Volo.Abp.BlobStoring.csproj" />
+    <ProjectReference Include="..\Volo.Abp.Caching\Volo.Abp.Caching.csproj" />
+  </ItemGroup>
+
+</Project>

framework/src/Volo.Abp.BlobStoring.Aliyun/Volo/Abp/BlobStoring/Aliyun/AbpBlobStoringAliyunModule.cs

@@ -0,0 +1,14 @@
+using Volo.Abp.Caching;
+using Volo.Abp.Modularity;
+
+namespace Volo.Abp.BlobStoring.Aliyun
+{
+    [DependsOn(
+        typeof(AbpBlobStoringModule),
+        typeof(AbpCachingModule)
+        )]
+    public class AbpBlobStoringAliyunModule: AbpModule
+    {
+
+    }
+}

framework/src/Volo.Abp.BlobStoring.Aliyun/Volo/Abp/BlobStoring/Aliyun/AliyunBlobContainerConfigurationExtensions.cs

@@ -0,0 +1,25 @@
+using System;
+
+namespace Volo.Abp.BlobStoring.Aliyun
+{
+    public static class AliyunBlobContainerConfigurationExtensions
+    {
+        public static AliyunBlobProviderConfiguration GetAliyunConfiguration(
+            this BlobContainerConfiguration containerConfiguration)
+        {
+            return new AliyunBlobProviderConfiguration(containerConfiguration);
+        }
+
+        public static BlobContainerConfiguration UseAliyun(
+            this BlobContainerConfiguration containerConfiguration,
+            Action<AliyunBlobProviderConfiguration> aliyunConfigureAction)
+        {
+            containerConfiguration.ProviderType = typeof(AliyunBlobProvider);
+            containerConfiguration.NamingNormalizers.TryAdd<AliyunBlobNamingNormalizer>();
+
+            aliyunConfigureAction(new AliyunBlobProviderConfiguration(containerConfiguration));
+
+            return containerConfiguration;
+        }
+    }
+}

framework/src/Volo.Abp.BlobStoring.Aliyun/Volo/Abp/BlobStoring/Aliyun/AliyunBlobNamingNormalizer.cs

@@ -0,0 +1,51 @@
+using System.Text.RegularExpressions;
+using Volo.Abp.DependencyInjection;
+
+namespace Volo.Abp.BlobStoring.Aliyun
+{
+    public class AliyunBlobNamingNormalizer : IBlobNamingNormalizer, ITransientDependency
+    {
+        /// <summary>
+        /// Container names can contain only letters, numbers, and the dash (-) character 
+        /// they can't start or end with the dash (-) character 
+        /// Container names must be from 3 through 63 characters long
+        /// </summary>
+        public virtual string NormalizeContainerName(string containerName)
+        {
+            // All letters in a container name must be lowercase.
+            containerName = containerName.ToLower();
+
+            // Container names can contain only letters, numbers, and the dash (-) character.
+            containerName = Regex.Replace(containerName, "[^a-z0-9-]", string.Empty);
+
+            // Every dash (-) character must be immediately preceded and followed by a letter or number;
+            // consecutive dashes are not permitted in container names.
+            // Container names must start or end with a letter or number
+            containerName = Regex.Replace(containerName, "-{2,}", "-");
+            containerName = Regex.Replace(containerName, "^-", string.Empty);
+            containerName = Regex.Replace(containerName, "-$", string.Empty);
+
+            // Container names must be from 3 through 63 characters long.
+            if (containerName.Length < 3)
+            {
+                var length = containerName.Length;
+                for (var i = 0; i < 3 - length; i++)
+                {
+                    containerName += "0";
+                }
+            }
+
+            if (containerName.Length > 63)
+            {
+                containerName = containerName.Substring(0, 63);
+            }
+
+            return containerName;
+        }
+
+        public virtual string NormalizeBlobName(string blobName)
+        {
+            return blobName;
+        }
+    }
+}