Foundatio.JsonNet 10.7.1

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

• 缓存
• 队列
• 锁
• 消息传递
• 工作
• 文件存储
• 指标

包括 Redis、Azure、AWS、RabbitMQ、Kafka 以及内存中的实现（用于开发）。

为何选择 Foundatio？

在构建多个大型云应用程序时，我们发现缺乏出色的解决方案（这并不是说没有解决方案），无法构建可扩展的分布式应用程序，同时保持开发经验简单。以下是为什么我们构建并使用 Foundatio 的几个原因：

• 想要针对抽象接口进行构建，这样我们可以轻松地更改实现。
• 想要使块对依赖注入友好。
• 缓存：我们最初使用一个开源 Redis 缓存客户端，但后来它变成了一个带有高许可成本的商业产品。不仅如此，还没有内存中的实现，因此每个 разработчик 都需要设置和配置 Redis。
• 消息总线：我们最初考虑了NServiceBus（一款优秀的产品），但它的授权费用较高（他们也需要生存），且不是开源友好。我们还调查了MassTransit（另一款优秀的产品），但当时发现Azure支持不足，本地设置也很痛苦（对于内存存储）。我们想要一个简单的消息总线，只在工作本地或云计算中工作。
• 存储：我们没有找到任何现有的项目可以解耦并支持内存、文件存储或Azure Blob存储。

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

实现方式

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

入门（开发）

Foundatio可以通过NuGet包管理器进行安装。如果您需要帮助，请提交问题或加入我们的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 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 接口的基础上实现。我们还提供了一个你可以从中继承的基类 JobBase，它提供了作业上下文和日志记录。然后你可以通过在任务上调用 RunAsync() 方法或在创建 JobRunner 类的实例后调用其 Run 方法来运行任务。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。

感谢所有提供贡献的人