NServiceBus入门：发送一个命令（Introduction to NServiceBus: Sending a command）
原文地址：https://docs.particular.net/tutorials/intro-to-nservicebus/2-sending-a-command/
侵删。
能够发送和接收message是任何NServiceBus 系统的主要特征。在两个进程之间传递持久化的message能使这个传递更加可靠，哪怕其中一个进程暂时不可用。在这个课程中我们将会展示如何发送并且处理一个信息。在接下来的15-20分钟里，你会学到如何定义message和message handler，如何在本地发送和接收message并且使用内置的日志功能。
什么是message
message是一组数据，他们通过单向communication在两个endpoint之间传递。在NServiceBus中，我们将message定义成一个简单的类。
在这节课中，我们将会关注commands。在第四节课：发布事件中，我们会展开讲到event。
要定义一个command，先生成一个类然后让它继承ICommand标记接口。
public class DoSomething :
ICommand
{
public string SomeProperty { get; set; }
}这个标记接口没有实现任何方法，只是让NServiceBus 知晓这个类是一个command，因此它可以在开启一个endpoint的时候构建一些关于message类型的元数据。你在这个message中构建的任何属性都构成了message数据本身。
command类的名字一样也很重要。一个command是做一件事情的请求，因此它应当以一种祈使语气的方式来命名。PlaceOrder 和ChargeCreditCard 都是很好的command命名方式，因为他们看上去很像一个“请求”。PlaceOrder 将会下一个订单，而ChargeCreditCard 将会在信用卡中扣款。然而CustomerMessage就不是一个好名字。它只看失去不是那么像一个请求，并且不是非常一目了然。其他开发者应当一看名字就知道这个command的目的是什么。
command的名字也应当传递一些业务含义。UpdateCustomerPropertyXYZ虽然比CustomerMessage 更加一目了然，然而也不是一个好的command名字，因为它仅仅关注数据的操作而没有业务含义在里面。MarkCustomerAsGold，或者类似于这样的名字，就更加面向业务了——它也许是一个更加的选择。
当发送一个message的时候，endpoint的序列化工具会将DoSomething 类的实例序列化，然后把它添加到即将发出到队列的message中去。在另一头，接收方endpoint会将这个message反序列化成一个实例来在代码中使用。
message甚至可以包含一些子对象或者集合。（这个由序列化工具类型来决定）
public class DoSomethingComplex :
ICommand
{
public int SomeId { get; set; }
public ChildClass ChildStuff { get; set; }
public List<ChildClass> ListOfStuff { get; set; } = new List<ChildClass>();
}
public class ChildClass
{
public string SomeProperty { get; set; }
}message是两个endpoint之间的协议。message的任何改变都会对发送方和接收方产生影响。你的message中包含的的属性越多，就有越多产生变动的原因，因此确保你的message越精简越好。
同时你不能再你的message类中嵌入逻辑。每一个message都应该只包含自动属性不能有包含计算的属性或者方法。同样的，通过默认的无参构造函数来实例化集合属性也是一个很好的做法，就像上面那样，因此你永远不要担心会产生一个null的集合。
实际上，message应当只能包含数据。通过确保你的message足够小，并且赋予它清晰的目的，你就可以让你的代码更加容易理解和扩展。
组织messages
message是数据协议，他们在各个endpoint之间共享。因此你实际上不能把这些类放在各个endpoint的相同程序集中。他们应该在分布在不同的类库里。
message 的程序集应该是独立的，意味着他们应当仅仅包含NServiceBus message类型和任何被message自身需要的类型。例如，如果一个message使用了一个美剧类型作为他的一个属性，这个枚举类就也应该在message程序集中。
message程序集不应当依赖除了.NET Framework类库和NServiceBus 核心库之外的程序集，因为ICommand 接口位于NServiceBus 核心库中。
参照这些方法会让你的message协议在以后更加容易扩展。
处理message
我们构造了message handler来处理message，这个类实现了IHandleMessages<T>接口，T是一个message类型。一个message handler示例如下：
public class DoSomethingHandler :
IHandleMessages<DoSomething>
{
public Task Handle(DoSomething message, IMessageHandlerContext context)
{
// Do something with the message here
return Task.CompletedTask;
}
}IHandleMessages<T> 实现了一个handle方法，NServiceBus 将会在一个T类型的message（在DoSomething中）到达的时候调用这个方法。handle方法接收message和一个包含处理message上下文API的IMessageHandlerContext实现。
除了显式返回一个task，你也可以在一个handler方法前面添加async关键字：
public class DoSomethingHandler :
IHandleMessages<DoSomething>
{
public async Task Handle(DoSomething message, IMessageHandlerContext context)
{
// Do something with the message here
}
}如果你想要学习更多使用async 方法的构建handler方式，可以参阅Asynchronous Handlers。
一个类可以实现多个IHandleMessages<T>来处理多种message类型。这样就可以将一些逻辑上相关联的handler组成一组，尽管处理每个message都会实例化出一个新的对象。
public class DoSomethingHandler :
IHandleMessages<DoSomething>,
IHandleMessages<DoSomethingElse>
{
public Task Handle(DoSomething message, IMessageHandlerContext context)
{
Console.WriteLine("Received DoSomething");
return Task.CompletedTask;
}
public Task Handle(DoSomethingElse message, IMessageHandlerContext context)
{
Console.WriteLine("Received DoSomethingElse");
return Task.CompletedTask;
}
}当NServiceBus 开启的时候，它将会找到所有的这些message handler类并且自动将他们合并在一起，因此当message到的时候他们都会被调用。这里不需要进行任何的初始化和配置。
handler在一个类还是多各类中实现都是一样的。当NServiceBus 启动的时候，它会找到所有的message handler然后将他们合并在一起，不需要任何配置。这样的组合方法是为了让你的代码更加清晰。
练习
现在让我们继续使用上节课构建的解决方案，将它进行一些更改让它能够发送message。你也可以直接拿一个已经完成的上节课的例子来开始。
当我们完成的时候，ClientUI endpoint会向自己发送一个 PlaceOrder ，然后处理这个message，就像下面这个图描述的这样：
创建一个message程序集
为了在endpoint之间分享message，它们必须各自独立在不同的程序集中间，现在让我们来创建这些程序集。
1.在这个解决方案中，生成一个新的项目然后选择类库项目类型。
2.把项目的名称设置成Message
3.把自动生成的class1.cs文件删掉
4.添加 NServiceBus NuGet 包到这个项目中
5.在ClientUI 项目中，添加对Message项目的引用
创建一个message
我们将要在一个叫Commands的文件夹创建我们第一个command。
1.在Message项目中，创建一个新的叫做PlaceOrder的类
2.将PlaceOrder标记成public并且实现ICommand接口
3.添加一个string类型的公共OrderId属性
.NET Framework 在System.Windows.Input名称空间下面包含一个它定义的ICommand 接口。因此在你自动解析名称空间的时候，你要选择NServiceBus.ICommand。大多数你需要的类型都会在NServiceBus名称空间中。
完成之后，你的PlaceOrder 类应该是这样子的：
namespace Messages
{
public class PlaceOrder :
ICommand
{
public string OrderId { get; set; }
}
}创建一个handler
现在我们已经定义了一个message了，我们可以创建一个相应的message handler。现在，然我们处理在ClientUI endpoint本地的message。
1.在ClientUI 项目中，创建一个叫做PlaceOrderHandler的类。
2.将这个handler类定义成public，然后实现IHandleMessages<PlaceOrder>接口。
3.添加一个日志实例，这能够让你使用和NServiceBus用的一样的日志系统。它在Console.WriteLine()上有一个很重要的优点：日志的信息都会在控制台上面展现。使用下面的代码将日志实例添加到你的handler类中：
static ILog logger = LogManager.GetLogger<PlaceOrderHandler>();4.在handle方法中，使用logger来记录PlaceOrder message的接收，包括OrderId 的值：
static ILog logger = LogManager.GetLogger<PlaceOrderHandler>();5.因为我们所有在这个handler中做的事情都是同步的，返回Task.CompletedTask.
完成之后，你的PlaceOrderHandler 类应该是这样子的：
public class PlaceOrderHandler :
IHandleMessages<PlaceOrder>
{
static ILog log = LogManager.GetLogger<PlaceOrderHandler>();
public Task Handle(PlaceOrder message, IMessageHandlerContext context)
{
log.Info($"Received PlaceOrder, OrderId = {message.OrderId}");
return Task.CompletedTask;
}
}因为LogManager.GetLogger(..); 的开销很大，所以请将logger实现作为成静态成员。
发送一个message
现在我们有了一个message和一个处理它的handler了，让我们来发送message。
在ClientUI 项目中，我们暂时先按回车键来终止endpoint。现在让我们来创建一个循环来让它更加具有互动性，我们可以使用键盘输入来决定是发送message还是退出。
将下面的方法添加到Program.cs 文件中：
static ILog log = LogManager.GetLogger<Program>();
static async Task RunLoop(IEndpointInstance endpointInstance)
{
while (true)
{
log.Info("Press 'P' to place an order, or 'Q' to quit.");
var key = Console.ReadKey();
Console.WriteLine();
switch (key.Key)
{
case ConsoleKey.P:
// Instantiate the command
var command = new PlaceOrder
{
OrderId = Guid.NewGuid().ToString()
};
// Send the command to the local endpoint
log.Info($"Sending PlaceOrder command, OrderId = {command.OrderId}");
await endpointInstance.SendLocal(command)
.ConfigureAwait(false);
break;
case ConsoleKey.Q:
return;
default:
log.Info("Unknown input. Please try again.");
break;
}
}
}当我们想要下一个订单的时候，我们先仔细地观察这个例子。为了生成一个 PlaceOrder 的command，我们简单地实例化一个PlaceOrder 类，然后给OrderId一个唯一值。记录完这些细节的之后，我们可以通过调用SendLocal 方法来发送它。
SendLocal(object message)是一个定义在IEndpointInstance 接口的方法，就像我们在这里使用的，它也定义在IMessageHandlerContext 接口中，这个接口在我们定义我们的message handler的时候我们也见到过。Local 意味着我们不把message发送到外面的endpoint去（位于一个不同的进程），因此我们倾向于在发送同时也接收message的endpoint中处理它。使用SendLocal(), 我们不需要其他任何的信息告诉message它要被发送到哪里。
在这节课程中，我们使用了SendLocal(而不是其他的更加常用的Send方法）。这样我们可以探索如何定义，发送和处理message，不需要第二个endpoint来处理它们。通过SendLocal方法，我们也不需要定义路由规则来控制这个message发送到哪里。我们将会在下一个课程中学习这些东西。
因为SendLocal() 返回一个Task，我们需要保证合理地await它。
现在让我们修改这个AsyncMain ，调用新的RunLoop 方法：
var endpointInstance = await Endpoint.Start(endpointConfiguration)
.ConfigureAwait(false);
// Remove these two lines
Console.WriteLine("Press Enter to exit...");
Console.ReadLine();
// Replace with:
await RunLoop(endpointInstance);
await endpointInstance.Stop()
.ConfigureAwait(false);运行解决方案
现在我们可以运行这个解决方案。我们只要在控制台中输入P，一个command message就会被发送然后在同一个项目中的handler里面处理。
INFO ClientUI.Program Press 'P' to place an order, or 'Q' to quit.
p
INFO ClientUI.Program Sending PlaceOrder command, OrderId = 1fb61e01-34a3-4562-82b1-85278565b59d
INFO ClientUI.Program Press 'P' to place an order, or 'Q' to quit.
INFO ClientUI.PlaceOrderHandler Received PlaceOrder, OrderId = 1fb61e01-34a3-4562-82b1-85278565b59d
p
INFO ClientUI.Program Sending PlaceOrder command, OrderId = d9e59362-ccf4-4323-8298-4bbc052fb877
INFO ClientUI.Program Press 'P' to place an order, or 'Q' to quit.
INFO ClientUI.PlaceOrderHandler Received PlaceOrder, OrderId = d9e59362-ccf4-4323-8298-4bbc052fb877需要注意的是在发送message之后，ClientUI.Program的提示在ClientUI.PlaceOrderHandler 确认接收到message之后显示。这个是因为和直接调用Handle方法不一样，这个message是异步发送的，然后控制台立即返回到RunLoop（这个方法会立即重复提示出信息）。很快，当message被接收和处理之后，我们会看到Received PlaceOrder 的提示。
总结
在这节课中我们学习了关于message，message的程序集和message handler。我们创建了一个message和一个handler然后我们使用SendLocal() 方法来发送message到同一个endpoint中。
在下节课中，我们会创建第二个messaging endpoint，将我们的message处理转移到那里去。然后我们将会配置ClientUI ，将message发送到新的endpoint中。我们也会观察如何接受方endpoint不在线的时候我们发送message过去会发生什么。
