Righthand.Vice.Bridge 1.0.1

VICE 二进制监视器桥接器 for .NET

一个支持跨平台 .NET 8.0 的库，该库实现了与 VICE 二进制监视器 通信的桥梁。

主	开发

测试（在 Windows 10 上有限制）并与 VICE 3.7 进行构建。

重要：目前，它只能与 API v1 一起使用，不能与 API v2 一起使用，而 API v2 至少在 VICE 3.7 中实现了。

快速入门

使用 -binarymonitor 参数启动 VICE，以便它监听默认端口 6502。

第一步是使用 .NET 的标准 Microsoft.Extensions.DependencyInjection.IServiceCollection 通过调用扩展方法 Righthand.ViceMonitor.Bridge.AddEngineServices 注册类型，如下所示

var collection = new ServiceCollection();
collection.AddEngineServices();

在 IoC 设置后，必须通过 IoC 解决 IViceBridge。可选地，可以使用 ConnectionChanged 事件处理器来跟踪连接状态（也可通过 IViceBridge.IsConnected 属性获取）和 ViceResponse 事件处理器来接收 VICE 之间的未绑定响应。

bridge.ConnectedChanged += Bridge_ConnectedChanged;
bridge.Start();

当 IViceBridge.IsConnected 属性变为 true 后，可以向 VICE 发送命令，并且响应将返回。这里是一个 ping 命令。

var ping = bridge.EnqueueCommand(new PingCommand());
var commandResponse = await ping.Response;
if (commandResponse.IsSuccess)
{
	// response is of type PingCommand expects
	var response = cr.Response;
	...
}
else
{
	Console.WriteLine($"An error with code {commandResponse.ErrorCode} occurred");
}

内部工作原理的更多介绍

库使用了 .NET 的 Microsoft.Extensions.DependencyInjection IoC 系统，并且在启动 ViceBridge 之前必须初始化它。

客户端通常创建不可变命令并将它们入队到桥接器中。ViceBridge 将按先进先出 (FIFO) 的方式处理这些命令。一旦命令发送到 VICE，桥接器将匹配发出的命令（或在某些情况下匹配多个响应）。当客户端想要读取 VICE 的响应或等待它时，它可以对 ViceCommand.Response 任务进行 await。

命令使用 Righthand.ViceMonitor.Bridge.Commands 命名空间，并根据 VICE 的二进制协议进行了建模，并在可能的地方进行了一些改进。例如，不需要 FileNameIndex，因为它可以从 FileName 字符串属性中读取。

内部用于输入和输出的字节数组通过自定义的 BufferManager 类从 ArrayPool<byte>.Shared 获取，并通过 ManagedBuffer 类打包。一些属性公开了 said ManagedBuffer。请阅读下面的内存管理章节以避免内存泄漏。

与任何命令无关的响应可以通过 IViceBridge.ViceResponse 事件访问。响应使用 Righthand.ViceMonitor.Bridge.Responses 命名空间。

内存管理

调用者必须在处理完所有数据后清理实现 IDisposable 的响应。通常，这些响应至少有一个 ManagedBuffer 类型的属性，它从共享池中借用字节数组。如果未在响应上调用 Dispose()，则会导致内存泄漏。

在撰写本文时，只有两种这样的响应： MemoryGetResponse 和 DisplayGetResponse。

当将 ManagedBuffer 实例传递给命令时，ViceBridge 将丢弃该命令以及所提供的 ManagedBuffer。一旦命令入队，调用者就不再可以修改所传递的 ManagedBuffer，因为在未知的时间点它可能会被销毁。

在撰写本文时，只有一个这样的命令： MemorySetCommand。

游乐场示例

游乐场示例是一个用于测试和演示目的的控制台应用程序。它演示了基础知识和一些简单任务。