docs/mxaccess-worker-instance-design.md

@@ -26,6 +26,33 @@ Style guides:
 - [C# Style Guide](./style-guides/CSharpStyleGuide.md)
 - [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md)
 
+## Build And Test
+
+Build the SDK-style worker project with the .NET SDK MSBuild entry point. The
+project targets .NET Framework 4.8, but the SDK resolver comes from the .NET SDK
+installation:
+
+```powershell
+dotnet msbuild src\MxGateway.Worker\MxGateway.Worker.csproj /restore /p:Configuration=Debug /p:Platform=x86
+```
+
+`docs/toolchain-links.md` records the Visual Studio MSBuild executable for
+classic .NET Framework and COM interop builds:
+
+```powershell
+& "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin\MSBuild.exe" src\MxGateway.Worker\MxGateway.Worker.csproj /p:Configuration=Debug /p:Platform=x86
+```
+
+Run the worker tests with the same platform target:
+
+```powershell
+dotnet test src\MxGateway.Worker.Tests\MxGateway.Worker.Tests.csproj -p:Platform=x86
+```
+
+The only MXAccess interop reference belongs in `MxGateway.Worker`. Gateway and
+test projects may reference the worker project for metadata and scaffold tests,
+but they must not reference `ArchestrA.MXAccess.dll` directly.
+
 ## Responsibilities
 
 The worker owns:

src/MxGateway.Contracts/MxGateway.Contracts.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net10.0</TargetFramework>
+    <TargetFrameworks>net10.0;net48</TargetFrameworks>
   </PropertyGroup>
 
   <ItemGroup>
@@ -17,6 +17,7 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
       <PrivateAssets>all</PrivateAssets>
     </PackageReference>
+    <PackageReference Include="System.Runtime.CompilerServices.Unsafe" Version="6.1.2" />
   </ItemGroup>
 
 </Project>

src/MxGateway.Worker.Tests/Contracts/WorkerContractInfoTests.cs

@@ -0,0 +1,19 @@
+using MxGateway.Contracts;
+using MxGateway.Worker.Ipc;
+
+namespace MxGateway.Worker.Tests.Contracts;
+
+public sealed class WorkerContractInfoTests
+{
+    [Fact]
+    public void SupportedProtocolVersion_UsesSharedGatewayContractVersion()
+    {
+        Assert.Equal(GatewayContractInfo.WorkerProtocolVersion, WorkerContractInfo.SupportedProtocolVersion);
+    }
+
+    [Fact]
+    public void WorkerEnvelopeDescriptorName_UsesGeneratedWorkerContract()
+    {
+        Assert.Equal("mxaccess_worker.v1.WorkerEnvelope", WorkerContractInfo.WorkerEnvelopeDescriptorName);
+    }
+}

src/MxGateway.Worker.Tests/MxAccess/MxAccessInteropInfoTests.cs

@@ -0,0 +1,23 @@
+using MxGateway.Worker.MxAccess;
+
+namespace MxGateway.Worker.Tests.MxAccess;
+
+public sealed class MxAccessInteropInfoTests
+{
+    [Fact]
+    public void InteropInfo_IdentifiesInstalledMxAccessComTarget()
+    {
+        Assert.Equal("LMXProxy.LMXProxyServer.1", MxAccessInteropInfo.ProgId);
+        Assert.Equal("LMXProxy.LMXProxyServer", MxAccessInteropInfo.VersionIndependentProgId);
+        Assert.Equal("{C30B52F5-2CB5-4760-AF0A-3A344A7EB5DC}", MxAccessInteropInfo.Clsid);
+        Assert.Equal("ArchestrA.MxAccess.LMXProxyServerClass", MxAccessInteropInfo.ComClassName);
+    }
+
+    [Fact]
+    public void InteropAssemblyName_ComesFromReferencedMxAccessAssembly()
+    {
+        Assert.Equal("ArchestrA.MxAccess", MxAccessInteropInfo.InteropAssemblyName);
+        Assert.Equal(3, MxAccessInteropInfo.InteropAssemblyVersion.Major);
+        Assert.Equal(2, MxAccessInteropInfo.InteropAssemblyVersion.Minor);
+    }
+}

src/MxGateway.Worker.Tests/MxGateway.Worker.Tests.csproj

@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net48</TargetFramework>
+    <IsPackable>false</IsPackable>
+    <PlatformTarget>x86</PlatformTarget>
+    <Prefer32Bit>true</Prefer32Bit>
+    <ImplicitUsings>disable</ImplicitUsings>
+    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
+    <GenerateBindingRedirectsOutputType>true</GenerateBindingRedirectsOutputType>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="System.Runtime.CompilerServices.Unsafe" Version="6.1.2" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\MxGateway.Worker\MxGateway.Worker.csproj" />
+  </ItemGroup>
+
+</Project>

src/MxGateway.Worker.Tests/ProjectStructure/WorkerProjectReferenceTests.cs

@@ -0,0 +1,94 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Xml.Linq;
+
+namespace MxGateway.Worker.Tests.ProjectStructure;
+
+public sealed class WorkerProjectReferenceTests
+{
+    [Fact]
+    public void WorkerProject_TargetsNet48AndX86()
+    {
+        XDocument project = LoadProject("MxGateway.Worker");
+
+        Assert.Equal("net48", ElementValue(project, "TargetFramework"));
+        Assert.Equal("x86", ElementValue(project, "PlatformTarget"));
+        Assert.Equal("true", ElementValue(project, "Prefer32Bit"));
+    }
+
+    [Fact]
+    public void WorkerTestProject_TargetsNet48AndX86()
+    {
+        XDocument project = LoadProject("MxGateway.Worker.Tests");
+
+        Assert.Equal("net48", ElementValue(project, "TargetFramework"));
+        Assert.Equal("x86", ElementValue(project, "PlatformTarget"));
+    }
+
+    [Fact]
+    public void MxAccessInteropReference_ExistsOnlyInWorkerProject()
+    {
+        DirectoryInfo repositoryRoot = FindRepositoryRoot();
+        string[] projectFiles = Directory.GetFiles(repositoryRoot.FullName, "*.csproj", SearchOption.AllDirectories)
+            .Where(path => path.IndexOf($"{Path.DirectorySeparatorChar}bin{Path.DirectorySeparatorChar}", StringComparison.OrdinalIgnoreCase) < 0)
+            .Where(path => path.IndexOf($"{Path.DirectorySeparatorChar}obj{Path.DirectorySeparatorChar}", StringComparison.OrdinalIgnoreCase) < 0)
+            .ToArray();
+
+        IReadOnlyList<string> projectsWithMxAccessReference = projectFiles
+            .Where(ProjectReferencesMxAccess)
+            .Select(path => Path.GetFileNameWithoutExtension(path))
+            .ToArray();
+
+        Assert.Equal(["MxGateway.Worker"], projectsWithMxAccessReference);
+    }
+
+    private static bool ProjectReferencesMxAccess(string projectPath)
+    {
+        XDocument project = XDocument.Load(projectPath);
+
+        return project
+            .Descendants()
+            .Where(element => element.Name.LocalName is "Reference" or "COMReference" or "COMFileReference" or "PackageReference")
+            .Select(element => (string?)element.Attribute("Include") ?? string.Empty)
+            .Concat(project.Descendants().Where(element => element.Name.LocalName == "HintPath").Select(element => element.Value))
+            .Any(reference =>
+                reference.IndexOf("MxAccess", StringComparison.OrdinalIgnoreCase) >= 0
+                || reference.IndexOf("ArchestrA.MXAccess", StringComparison.OrdinalIgnoreCase) >= 0
+                || reference.IndexOf("LMXProxy", StringComparison.OrdinalIgnoreCase) >= 0);
+    }
+
+    private static XDocument LoadProject(string projectName)
+    {
+        DirectoryInfo repositoryRoot = FindRepositoryRoot();
+        string projectPath = Path.Combine(repositoryRoot.FullName, projectName, $"{projectName}.csproj");
+
+        return XDocument.Load(projectPath);
+    }
+
+    private static string ElementValue(XDocument project, string elementName)
+    {
+        return project
+            .Descendants()
+            .Single(element => element.Name.LocalName == elementName)
+            .Value;
+    }
+
+    private static DirectoryInfo FindRepositoryRoot()
+    {
+        DirectoryInfo? current = new(AppContext.BaseDirectory);
+
+        while (current is not null)
+        {
+            if (File.Exists(Path.Combine(current.FullName, "MxGateway.sln")))
+            {
+                return current;
+            }
+
+            current = current.Parent;
+        }
+
+        throw new DirectoryNotFoundException("Could not locate src/MxGateway.sln from the test output directory.");
+    }
+}

src/MxGateway.Worker/Bootstrap/.gitkeep

@@ -0,0 +1 @@
+

src/MxGateway.Worker/Conversion/.gitkeep

@@ -0,0 +1 @@
+

src/MxGateway.Worker/Ipc/WorkerContractInfo.cs

@@ -0,0 +1,11 @@
+using MxGateway.Contracts;
+using MxGateway.Contracts.Proto;
+
+namespace MxGateway.Worker.Ipc;
+
+public static class WorkerContractInfo
+{
+    public static uint SupportedProtocolVersion => GatewayContractInfo.WorkerProtocolVersion;
+
+    public static string WorkerEnvelopeDescriptorName => WorkerEnvelope.Descriptor.FullName;
+}

src/MxGateway.Worker/MxAccess/MxAccessInteropInfo.cs

@@ -0,0 +1,27 @@
+using System;
+using ArchestrA.MxAccess;
+
+namespace MxGateway.Worker.MxAccess;
+
+public static class MxAccessInteropInfo
+{
+    public const string ProgId = "LMXProxy.LMXProxyServer.1";
+
+    public const string VersionIndependentProgId = "LMXProxy.LMXProxyServer";
+
+    public const string Clsid = "{C30B52F5-2CB5-4760-AF0A-3A344A7EB5DC}";
+
+    public const string InteropAssemblyPath =
+        @"C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll";
+
+    public const string RegisteredServerPath =
+        @"C:\Program Files (x86)\ArchestrA\Framework\Bin\LmxProxy.dll";
+
+    public const string ComClassName = "ArchestrA.MxAccess.LMXProxyServerClass";
+
+    public static string InteropAssemblyName =>
+        typeof(LMXProxyServerClass).Assembly.GetName().Name ?? string.Empty;
+
+    public static Version InteropAssemblyVersion =>
+        typeof(LMXProxyServerClass).Assembly.GetName().Version ?? new Version(0, 0);
+}

src/MxGateway.Worker/MxGateway.Worker.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net48</TargetFramework>
+    <PlatformTarget>x86</PlatformTarget>
+    <Prefer32Bit>true</Prefer32Bit>
+    <ImplicitUsings>disable</ImplicitUsings>
+    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
+    <GenerateBindingRedirectsOutputType>true</GenerateBindingRedirectsOutputType>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\MxGateway.Contracts\MxGateway.Contracts.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Reference Include="ArchestrA.MxAccess">
+      <HintPath>C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll</HintPath>
+      <Private>false</Private>
+      <SpecificVersion>false</SpecificVersion>
+    </Reference>
+  </ItemGroup>
+
+</Project>

src/MxGateway.Worker/Program.cs

@@ -0,0 +1,3 @@
+using MxGateway.Worker;
+
+return WorkerApplication.Run(args);

src/MxGateway.Worker/Sta/.gitkeep

@@ -0,0 +1 @@
+

src/MxGateway.Worker/WorkerApplication.cs

@@ -0,0 +1,16 @@
+using System;
+
+namespace MxGateway.Worker;
+
+public static class WorkerApplication
+{
+    public static int Run(string[] args)
+    {
+        if (args is null)
+        {
+            throw new ArgumentNullException(nameof(args));
+        }
+
+        return 0;
+    }
+}

src/MxGateway.sln

@@ -11,6 +11,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Tests", "MxGatewa
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.IntegrationTests", "MxGateway.IntegrationTests\MxGateway.IntegrationTests.csproj", "{6D0BDEA5-F3F5-4F7C-9152-040BF88E4F2D}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Worker", "MxGateway.Worker\MxGateway.Worker.csproj", "{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Worker.Tests", "MxGateway.Worker.Tests\MxGateway.Worker.Tests.csproj", "{91255F30-8D43-47C9-AC52-AA0DDA4E9348}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -69,6 +73,30 @@ Global
 		{6D0BDEA5-F3F5-4F7C-9152-040BF88E4F2D}.Release|x64.Build.0 = Release|Any CPU
 		{6D0BDEA5-F3F5-4F7C-9152-040BF88E4F2D}.Release|x86.ActiveCfg = Release|Any CPU
 		{6D0BDEA5-F3F5-4F7C-9152-040BF88E4F2D}.Release|x86.Build.0 = Release|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Debug|x64.Build.0 = Debug|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Debug|x86.Build.0 = Debug|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Release|Any CPU.Build.0 = Release|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Release|x64.ActiveCfg = Release|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Release|x64.Build.0 = Release|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Release|x86.ActiveCfg = Release|Any CPU
+		{5F2E4C90-B101-4D5D-A9D4-F9F7B53C1A85}.Release|x86.Build.0 = Release|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Debug|x64.Build.0 = Debug|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Debug|x86.Build.0 = Debug|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Release|Any CPU.Build.0 = Release|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Release|x64.ActiveCfg = Release|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Release|x64.Build.0 = Release|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Release|x86.ActiveCfg = Release|Any CPU
+		{91255F30-8D43-47C9-AC52-AA0DDA4E9348}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE