Foundatio.AWS 10.7.1

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

• 缓存
• 队列
• 锁定
• 消息传递
• 作业
• 文件存储
• 度量

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

为什么选择Foundatio？

在构建几个大型云应用时，我们发现缺乏优秀的解决方案（这并不意味着没有解决方案），这些方案在构建可扩展的分布式应用时，既保持了简单的开发体验。以下是why we built and use Foundatio的几个例子。

• 希望针对抽象接口构建，以便我们能够轻松更改实现。
• 希望块对依赖注入友好。
• 缓存：我们最初使用的是开源的Redis缓存客户端，但后来它变成了具有高许可费用的商业产品。不仅如此，它不支持内存实现，因此每个开发者都必须设置和配置Redis。
• 消息总线：我们最初考虑了NServiceBus（优秀的产品），但由于其高许可费用（他们也有生计要解决），对于开源不是特别友好。我们还考虑了MassTransit（另一个优秀的工具），但当时发现Azure支持不足，而本地设置却很麻烦（对于内存）。我们希望有一个简单易用的消息总线，无论是在本地还是云端都能够顺畅运行。
• 存储：我们找不到任何现有的项目能够提供解耦合且支持内存、文件存储或Azure Blob存储的功能。

总结一下，如果您希望开发测试无痛苦，同时允许您的应用进行扩展，请使用Foundatio！

实现

• Redis - 缓存、存储、队列、消息、锁、指标
• Azure存储 - 存储、队列
• Azure ServiceBus - 队列、消息
• AWS - 存储、队列、指标
• Kafka - 消息
• RabbitMQ - 消息
• Minio - 存储
• 阿里云 - 存储
• SshNet - 存储

入门指南（开发）

可以通过 NuGet包管理器 安装Foundatio。如果您需要帮助，请提交一个issue或加入我们的Discord聊天室。如果您有任何问题，我们随时都在这里帮忙！

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

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

使用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 Queue实现。
4. AzureStorageQueue：Azure Storage Queue实现。
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 接口。我们还提供了一个您可以从中继承以提供 JobContext 和日志记录的基础类：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. 工作项作业：工作项作业将在与其他工作项作业一起工作的作业池中运行。这种类型的作业非常适合不太经常发生但应该作为作业处理的事情（例如：删除具有许多子项的实体）。它将在您在 message bus 上发布消息时触发。作业必须从以下类继承：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的幻灯片和一个示例应用程序。

感谢所有贡献者