Foundatio.Redis 10.7.1

构建松散耦合分布式应用的模块化基础块。

• 缓存
• 队列
• 锁
• 消息
• 作业
• 文件存储
• 指标

包括Redis、Azure、AWS、RabbitMQ、Kafka和内存（开发）中的实现。

为什么选择Foundatio？

在构建几个大型云应用时，我们发现缺乏出色的解决方案（不是说不存在解决方案）来解决构建可伸缩分布式应用所需的关键部分，同时保持开发体验简单。以下是我们构建并使用Foundatio的几个原因示例

• 想要针对抽象接口进行构建，以便我们可以轻松地更改实现。
• 想要块对依赖注入友好。
• 缓存：我们最初使用开源Redis缓存客户端，但后来它变成了一个带有高许可成本的商业产品。不仅如此，还没有内存实现，因此每个开发人员都必须设置和配置Redis。
• 消息总线：我们最初考察了NServiceBus（优秀的产品），但由于其高昂的许可费用（他们也需要生存），并且不太友好开源软件（OSS），我们决定放弃。我们也考察了MassTransit（另一个优秀的产品），但当时发现Azure支持不全面，并且本地设置很麻烦（对于内存存储）。我们想要一个简单易用的消息总线，能适用于本地或云端。
• 存储：我们找不到任何现有项目是解耦合且支持内存存储、文件存储或Azure Blob存储的。

总结一下，如果您希望开发测试无忧，同时允许您的应用程序扩展，那么请使用Foundatio！

实现

• Redis - 缓存、存储、队列、消息传递、锁、度量
• Azure 存储服务 - 存储、队列
• Azure 服务总线 - 队列、消息传递
• AWS - 存储、队列、度量
• Kafka - 消息传递
• RabbitMQ - 消息传递
• Minio - 存储
• 阿里云存储服务 - 存储
• SshNet 存储服务 - 存储

入门（开发）

通过NuGet包管理器安装Foundatio。如果您需要帮助，请提交问题或者加入我们的Discord聊天室。如果您有任何问题，我们都随时为您提供帮助！

本节仅用于开发目的！如果您正在尝试使用Foundatio库，请从NuGet获取。

1. 您需要安装Visual Studio Code。
2. 打开 Foundatio.sln Visual Studio解决方案文件。

使用Foundatio

以下各节仅包含 Foundatio 可用功能的很小部分。我们建议您查看源代码以获取更多信息。如果您有任何问题或需要帮助，请告知我们！

缓存

缓存可以快速存储和访问数据，从而节省创建或获取数据的昂贵操作。我们提供四种不同的基于 ICacheClient 接口 的缓存实现。

1. InMemoryCacheClient：内存缓存客户端实现。此缓存实现仅在进程生命周期内有效。请注意，内存缓存客户端具有通过 MaxItems 属性缓存最近 X 项的能力。我们在 Exceptionless 中使用它以仅保存最后 250 个解析的 geoip 结果。
2. HybridCacheClient：此缓存实现使用 ICacheClient 和 InMemoryCacheClient 并使用 IMessageBus 来同步进程间的缓存。这可以带来 巨大的性能提升，因为当项存在于本地缓存中时，你将节省序列化操作和对远程缓存的调用。
3. RedisCacheClient：Redis缓存客户端实现。
4. RedisHybridCacheClient：HybridCacheClient的一个实现，使用RedisCacheClient作为ICacheClient，而使用RedisMessageBus作为IMessageBus。
5. ScopedCacheClient：这种缓存实现接受一个ICacheClient的实例和一个字符串scope。范围被添加到每个缓存键之前。这使得所有缓存键的划分变得非常简单，并且可以轻松删除。

示例

using Foundatio.Caching;

ICacheClient cache = new InMemoryCacheClient();
await cache.SetAsync("test", 1);
var value = await cache.GetAsync<int>("test");

队列

队列提供先入先出（FIFO）的消息传递。我们提供了四个不同的队列实现，它们都是基于IQueue接口的。

1. InMemoryQueue：内存队列实现。此队列实现仅在进程的生命周期内有效。
2. RedisQueue：Redis队列实现。
3. AzureServiceBusQueue：Azure Service Bus 队列实现。
4. AzureStorageQueue：Azure 存储队列实现。
5. SQSQueue：AWS SQS 实现。

示例

using Foundatio.Queues;

IQueue<SimpleWorkItem> queue = new InMemoryQueue<SimpleWorkItem>();

await queue.EnqueueAsync(new SimpleWorkItem {
    Data = "Hello"
});

var workItem = await queue.DequeueAsync();

锁

锁确保资源在任何给定时间只能由一个消费者访问。我们提供了两个不同的锁实现，这两个实现都是从ILockProvider接口派生出来的。

1. CacheLockProvider：使用缓存进行进程间通信的锁实现。
2. ThrottlingLockProvider：仅允许一定数量的锁通过。您可以使用此功能来限制对某些外部服务的API调用，并且该锁定机制将跨所有请求该锁的进程进行节流。
3. ScopedLockProvider：此锁实现接受一个ILockProvider的实例和一个字符串scope。范围被添加到每个锁键之前。这使得所有锁的划分变得非常简单，并且可以轻松释放。

值得注意的是，所有锁提供者都接受一个ICacheClient。这允许您确保代码在多台机器上正确锁定。

示例

using Foundatio.Lock;

ILockProvider locker = new CacheLockProvider(new InMemoryCacheClient(), new InMemoryMessageBus());
var testLock = await locker.AcquireAsync("test");
// ...
await testLock.ReleaseAsync();

ILockProvider throttledLocker = new ThrottlingLockProvider(new InMemoryCacheClient(), 1, TimeSpan.FromMinutes(1));
var throttledLock = await throttledLocker.AcquireAsync("test");
// ...
await throttledLock.ReleaseAsync();

消息

允许您发布和订阅流经您的应用程序的消息。我们提供了四个不同的消息总线实现，这些实现都是从IMessageBus接口派生出来的。

1. InMemoryMessageBus：内存消息总线实现。此消息总线实现仅在进程的生命周期内有效。
2. RedisMessageBus：Redis消息总线实现。
3. RabbitMQMessageBus：RabbitMQ 实现。
4. KafkaMessageBus：Kafka 实现。
5. AzureServiceBusMessageBus：Azure Service Bus实现的类。

示例

using Foundatio.Messaging;

IMessageBus messageBus = new InMemoryMessageBus();
await messageBus.SubscribeAsync<SimpleMessageA>(msg => {
  // Got message
});

await messageBus.PublishAsync(new SimpleMessageA { Data = "Hello" });

作业

允许您运行长时间运行的过程（进程内或进程外）而不用担心它会被提前终止。我们根据您的使用情况，提供三种不同的方式来定义工作。

1. 工作：所有工作都必须从 IJob 接口 继承。我们还有一个可从之继承的 JobBase 基类，它提供了工作上下文和日志记录。然后，您可以通过在任务上调用 RunAsync() 或通过创建一个 JobRunner 类 的实例并调用其中一种运行方法来运行任务。JobRunner 可以用于轻松地将您的任务作为 Azure Web 任务运行。

示例

using Foundatio.Jobs;

public class HelloWorldJob : JobBase {
  public int RunCount { get; set; }

  protected override Task<JobResult> RunInternalAsync(JobContext context) {
     RunCount++;
     return Task.FromResult(JobResult.Success);
  }
}

var job = new HelloWorldJob();
await job.RunAsync(); // job.RunCount = 1;
await job.RunContinuousAsync(iterationLimit: 2); // job.RunCount = 3;
await job.RunContinuousAsync(cancellationToken: new CancellationTokenSource(10).Token); // job.RunCount > 10;

2. 队列处理器工作：队列处理器工作非常适合处理将来自队列数据的工作。队列处理器任务必须从 QueueJobBase<T> 类 继承。然后，您可以通过在任务上调用 RunAsync() 或将其传递给 JobRunner 类 来运行任务。JobRunner 可以用于轻松地将您的任务作为 Azure Web 任务运行。

示例

using Foundatio.Jobs;

public class HelloWorldQueueJob : QueueJobBase<HelloWorldQueueItem> {
  public int RunCount { get; set; }

  public HelloWorldQueueJob(IQueue<HelloWorldQueueItem> queue) : base(queue) {}

  protected override Task<JobResult> ProcessQueueEntryAsync(QueueEntryContext<HelloWorldQueueItem> context) {
     RunCount++;

     return Task.FromResult(JobResult.Success);
  }
}

public class HelloWorldQueueItem {
  public string Message { get; set; }
}

 // Register the queue for HelloWorldQueueItem.
container.AddSingleton<IQueue<HelloWorldQueueItem>>(s => new InMemoryQueue<HelloWorldQueueItem>());

// To trigger the job we need to queue the HelloWorldWorkItem message.
// This assumes that we injected an instance of IQueue<HelloWorldWorkItem> queue

IJob job = new HelloWorldQueueJob();
await job.RunAsync(); // job.RunCount = 0; The RunCount wasn't incremented because we didn't enqueue any data.

await queue.EnqueueAsync(new HelloWorldWorkItem { Message = "Hello World" });
await job.RunAsync(); // job.RunCount = 1;

await queue.EnqueueAsync(new HelloWorldWorkItem { Message = "Hello World" });
await queue.EnqueueAsync(new HelloWorldWorkItem { Message = "Hello World" });
await job.RunUntilEmptyAsync(); // job.RunCount = 3;

3. 工作项工作：工作项工作将在工作池中与其他工作项工作一起运行。此类任务非常适合不常发生但应在工作（例如：删除具有许多子实体的实体）中的情况。当您在 消息总线上发布消息时，它将被触发。工作必须从 WorkItemHandlerBase 类 继承。然后，您可以通过 JobRunner 类 运行所有共享工作。JobRunner 可以用于轻松地将您的任务作为 Azure Web 任务运行。

示例

using System.Threading.Tasks;
using Foundatio.Jobs;

public class HelloWorldWorkItemHandler : WorkItemHandlerBase {
  public override async Task HandleItemAsync(WorkItemContext ctx) {
    var workItem = ctx.GetData<HelloWorldWorkItem>();

    // We can report the progress over the message bus easily.
    // To receive these messages just inject IMessageSubscriber
    // and Subscribe to messages of type WorkItemStatus
    await ctx.ReportProgressAsync(0, "Starting Hello World Job");
    await Task.Delay(TimeSpan.FromSeconds(2.5));
    await ctx.ReportProgressAsync(50, "Reading value");
    await Task.Delay(TimeSpan.FromSeconds(.5));
    await ctx.ReportProgressAsync(70, "Reading value");
    await Task.Delay(TimeSpan.FromSeconds(.5));
    await ctx.ReportProgressAsync(90, "Reading value.");
    await Task.Delay(TimeSpan.FromSeconds(.5));

    await ctx.ReportProgressAsync(100, workItem.Message);
  }
}

public class HelloWorldWorkItem {
  public string Message { get; set; }
}

// Register the shared job.
var handlers = new WorkItemHandlers();
handlers.Register<HelloWorldWorkItem, HelloWorldWorkItemHandler>();

// Register the handlers with dependency injection.
container.AddSingleton(handlers);

// Register the queue for WorkItemData.
container.AddSingleton<IQueue<WorkItemData>>(s => new InMemoryQueue<WorkItemData>());

// The job runner will automatically look for and run all registered WorkItemHandlers.
new JobRunner(container.GetRequiredService<WorkItemJob>(), instanceCount: 2).RunInBackground();

 // To trigger the job we need to queue the HelloWorldWorkItem message.
 // This assumes that we injected an instance of IQueue<WorkItemData> queue

 // NOTE: You may have noticed that HelloWorldWorkItem doesn't derive from WorkItemData.
 // Foundatio has an extension method that takes the model you post and serializes it to the
 // WorkItemData.Data property.
 await queue.EnqueueAsync(new HelloWorldWorkItem { Message = "Hello World" });

文件存储

我们提供不同类型的文件存储实现，这些实现从 IFileStorage 接口 继承。

1. InMemoryFileStorage：内存文件实现。这种文件存储实现仅在进程生命周期内有效。
2. FolderFileStorage：使用硬盘进行存储的文件存储实现。
3. AzureFileStorage：Azure Blob 存储实现。
4. S3FileStorage：AWS S3 文件存储实现。
5. RedisFileStorage：Redis 文件存储实现。
6. MinioFileStorage：Minio 文件存储实现。
7. AliyunFileStorage：阿里云文件存储实现。
8. SshNetFileStorage：SFTP 文件存储实现。

我们建议将所有 IFileStorage 实现作为单例使用。

示例

using Foundatio.Storage;

IFileStorage storage = new InMemoryFileStorage();
await storage.SaveFileAsync("test.txt", "test");
string content = await storage.GetFileContentsAsync("test.txt")

指标

我们提供了五种实现，这些实现都是基于 IMetricsClient 界面 的。

1. InMemoryMetricsClient：内存指标实现。
2. RedisMetricsClient：Redis指标实现。
3. StatsDMetricsClient：statsd指标实现。
4. MetricsNETClient：一个 Metrics.NET 实现。
5. AppMetricsClient：一个 AppMetrics 实现。
6. CloudWatchMetricsClient：AWS CloudWatch实现。

我们建议将所有 IMetricsClient 实现 都作为单例使用。

示例

IMetricsClient metrics = new InMemoryMetricsClient();
metrics.Counter("c1");
metrics.Gauge("g1", 2.534);
metrics.Timer("t1", 50788);

示例应用程序

我们提供了幻灯片 和一个示例应用程序，展示了如何使用Foundatio。

感谢所有贡献者