AWS.AspNetCore.DistributedCacheProvider 0.9.3

AWS .NET 分布式缓存提供程序

The AWS .NET Distributed Cache Provider 提供了由 Amazon DynamoDB 支持的 ASP.NET Core 接口 IDistributedCache 的实现。IDistributedCache 实现的常用场景是在 ASP.NET Core 应用程序中存储临时、非关键 会话状态 数据。

入门

从 NuGet 中安装 AWS.AspNetCore.DistributedCacheProvider 包。

.NET 使用 依赖注入 为依赖于它们的不同对象提供服务。此库提供了扩展，帮助用户将此 IDistributedCache 实现注入为服务，以便其他对象使用。

示例

例如，如果您正在构建一个需要在分布式Web应用中使用会话的应用程序，.NET 的会话状态中间件将寻找 IDistributedCache 实现以存储会话数据。您可以通过依赖注入将会话服务设置为使用 DynamoDB 分布式缓存实现。

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAWSDynamoDBDistributedCache(options =>
{
    options.TableName = "session_cache_table";
    options.PartitionKeyName = "id";
    options.TTLAttributeName = "cache_ttl";

});
builder.Services.AddSession(options =>
{
    options.IdleTimeout = TimeSpan.FromSeconds(90);
    options.Cookie.IsEssential = true;
});
var app = builder.Build();
...

有关 .NET 会话状态中间件的更多信息，请参阅这篇文章，特别是有关依赖注入的这部分内容。

配置

以下是配置 DynamoDBDistributedCache 可用的选项。

• TableName（必需）- 字符串 - 将用于存储缓存数据的现有表的名称。
• CreateTableIfNotExists（可选）- 布尔值 - 如果在启动时设置为 true，则库将检查指定的表是否存在。如果表不存在，则将创建一个新的表并使用按需规范吞吐量。这将需要额外的权限来调用 CreateTable 和 UpdateTimeToLive 服务操作。建议仅在开发环境中将其设置为 true。生产环境应在部署前创建表。这将允许生产部署需要更少的权限并且启动速度更快。默认值是 false。
• UseConsistentReads（可选）- 布尔值 - 当设置为 true 时，从底层 DynamoDB 表的读取将使用一致读取。拥有一致读取意味着任何读取都将来自 DynamoDB 表中的最新数据。但是，使用一致读取需要更多的读取容量，这将影响 DynamoDB 表的成本。为了降低成本，可以将此属性设置为 false，但应用程序必须能够处理在设置操作后数据返回到获取操作内的延迟。默认值是 true。更多信息请参阅这里。
• PartitionKeyName（可选）- 字符串 - DynamoDB 表的分区键名称。如果不设置，启动时将进行 DescribeTable 服务调用以确定分区键的名称。为了减少启动时间和避免需要 DescribeTable 的权限，应设置此属性。
• PartitionKeyPrefix（可选）- 字符串 - 添加到 DynamoDB 中存储的分区键值的哈希前缀。
• TTLAttributeName（可选）- 字符串 - DynamoDB 的生存时间（TTL）功能用于从表中删除过期的缓存项。此选项指定用于存储 TTL 时间戳的属性名称。如果不设置，则将进行 DescribeTimeToLive 服务调用以确定 TTL 属性的名称。为了减少启动时间和避免需要 DescribeTimeToLive 的权限，应设置此属性。

可以使用以下方式使用这些选项。

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAWSDynamoDBDistributedCache(options =>
{
    options.TableName = "session_cache_table";
    options.CreateTableIfNotExists = true;
    options.UseConsistentReads = true;
    options.PartitionKeyName = "id";
    options.TTLAttributeName = "cache_ttl"

});
builder.Services.AddSession(options =>
{
    options.IdleTimeout = TimeSpan.FromSeconds(90);
    options.Cookie.IsEssential = true;
});
var app = builder.Build();
...

表考虑事项

如果指定了 TableName 的表已存在，缓存提供程序将使用该表。该表必须使用类型为字符串的非复合分区键，否则在第一次缓存操作期间将抛出异常。现有的表不会有任何设置被修改。

对于生产环境，我们建议将 CreateTableIfNotExists 设置为 false 并提供 PartitionKeyName 和 TTLAttributeName。这最小化了第一次缓存操作所需的权限和额外的控制平面调用。建议仅在开发环境中将 CreateTableIfNotExists 设置为 true。

当 CreateTableIfNotExists 设置为 true 并且 TableName 指定的表不存在时，第一个缓存操作中，缓存提供程序将使用以下默认设置创建一个表：

• 按需容量模式（点击查看）
• 启用生存时间（TTL）
• 使用DynamoDB拥有的并管理的AWS KMS密钥进行加密。如果您希望使用AWS管理的或客户管理的密钥，可以在创建表后更新密钥或提供自己的表。请参阅Amazon DynamoDB开发者指南中的管理加密表。

权限

要使用与现有DynamoDB表以及提供的PartitionKeyName和TTLAttributeName一起的缓存提供程序，需要以下权限

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "dynamodb:PutItem",
                "dynamodb:DeleteItem",
                "dynamodb:GetItem",
                "dynamodb:UpdateItem"
            ],
            "Resource": "arn:aws:dynamodb:*:<account>:table/<table>"
        }
    ]
}

如果配置为使用现有表，但没有指定PartitionKeyName和TTLAttributeName，那么除了上述权限外，还需要以下权限

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "dynamodb:DescribeTable",
                "dynamodb:DescribeTimeToLive"
            ],
            "Resource": "arn:aws:dynamodb:*:<account>:table/<table>"
        }
    ]
}

如果缓存提供程序配置为通过上面描述的CreateTableIfNotExists选项创建表，那么除了上面指定的基础权限外，还需要以下权限

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "dynamodb:CreateTable",
                "dynamodb:UpdateTimeToLive"
            ],
            "Resource": "arn:aws:dynamodb:*:<account>:table/<table>"
        }
    ]
}

可以使用LeadingKeys条件选择性地限制对DynamoDB表中缓存条目的访问。可以通过上面的PartitionKeyPrefix选项配置前缀，默认值为"dc"。有关更多信息，请参阅使用IAM策略条件进行精细访问控制

    "Resource": "arn:aws:dynamodb:*:<acount>:table/<table>",
    "Condition": {
        "ForAllValues:StringLike": {
            "dynamodb:LeadingKeys": "dc:*"
        }
    }

生存时间

IDistributedCache在其DistributedCacheEntryOptions中公开了几种过期条目的选项。如果您使用IDistributedCache来存储ASP.NET Core应用程序的会话状态，则SessionOptions.IdleTimeout控制缓存条目的过期时间。

AWS .NET分布式缓存提供程序依赖DynamoDB的生存时间（TTL）功能来从表中删除过期的条目。通过CreateTableIfNotExists创建表时，将自动启用TTL。如果您提供了现有的表，并且TTL没有启用，则过期的条目将不会被删除，并且首次缓存操作期间将记录一条警告消息。

因为DynamoDB的TTL功能可能需要几天时间才能删除过期的条目，所以缓存提供程序会在客户端过滤掉那些已过期但尚未被删除的条目。

审计

默认情况下，当创建AWS账户时，CCloudTrail就会启用并会捕获DynamoDB的控制平面事件。

要捕获数据平面事件，请参阅AWS CloudTrail用户指南中的记录数据事件。

依赖

此库具有以下依赖项

• AWSSDK.DynamoDBv2
• AWSSDK.Extensions.NETCore.Setup
• Microsoft.Extensions.Caching.Abstractions
• Microsoft.Extensions.DependencyInjection.Abstractions
• Microsoft.Extensions.Options

获取帮助

我们使用GitHub问题来跟踪错误和功能请求，并有限的能力来处理它们。

如果您认为您可能找到了一个错误，请创建问题。

贡献

我们欢迎社区贡献和拉取请求。请参阅CONTRIBUTING.md以获取有关如何设置开发环境和提交代码的更多信息。

附加资源

AWS .NET GitHub主页面
此页面是.NET在AWS上开发的GitHub主页面。您将找到用于帮助您在AWS上构建.NET应用程序和服务的库、工具和资源。

AWS 开发者中心 - 在 AWS 上探索 .NET
在同一个地方找到所有所需的 .NET 代码示例、分步指南、视频、博客内容、工具和现场活动的信息。

AWS 开发者博客 - .NET
来看看 AWS 的 .NET 开发者在忙什么！了解新的 .NET 软件公告、指南和教程。

@dotnetonaws 在推特上关注我们！

安全性

AWS .NET 分布式缓存提供程序依靠 AWS SDK for .NET 与 AWS 进行通信。有关更多信息，请参考 安全部分 的 AWS SDK for .NET 开发者指南。

如果您发现潜在的安全问题，请参考 安全政策 报告信息。

许可证

此存储库中的库采用 Apache 2.0 许可证授权。

有关更多信息，请参阅 LICENSE 和 NOTICE。