RegFree COM example (#914)

* RegFree COM example

Author: AaronRobinsonMSFT

core/extensions/COMServerDemo/COMClient/COMClient.csproj

@@ -3,6 +3,9 @@
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>netcoreapp3.0</TargetFramework>
+
+    <!-- The application manifest is only needed for RegFree COM scenarios -->
+    <ApplicationManifest Condition="'$(RegFree)' == 'True'">COMClient.manifest</ApplicationManifest>
   </PropertyGroup>
 
   <ItemGroup>

core/extensions/COMServerDemo/COMClient/COMClient.manifest

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- https://docs.microsoft.com/windows/desktop/sbscs/assembly-manifests -->
+<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
+  <assemblyIdentity
+    type="win32" 
+    name="COMClient"
+    version="1.0.0.0" />
+
+  <dependency>
+    <dependentAssembly>
+      <!-- RegFree COM matching the registration of the generated managed COM server -->
+      <assemblyIdentity
+          type="win32"
+          name="COMServer.X"
+          version="1.0.0.0"/>
+    </dependentAssembly>
+  </dependency>
+
+</assembly>

core/extensions/COMServerDemo/COMServer/COMServer.csproj

@@ -5,17 +5,23 @@
         COM servers must define a framework to use in situations where a CLR instance is not already present in the process.
         Note that since the COM server may be activated in a process where the CLR must be activated, both the projects
         *.runtimeconfig.json and *.deps.json files must be bundled with the server itself.
-        
+
         In the following example, the following files are needed to deploy the COM server:
             COMServer.comhost.dll
             COMServer.dll
             COMServer.deps.json
             COMServer.runtimeconfig.json
+
+        In a RegFree COM scenario, the following file must also be deployed:
+            COMServer.X.manifest
     -->
     <TargetFramework>netcoreapp3.0</TargetFramework>
-    
+
     <!-- Indicate the assembly is providing a COM server -->
     <UseComHost>True</UseComHost>
+
+    <!-- Generate a RegFree COM manifest -->
+    <EnableRegFreeCom Condition="'$(RegFree)' == 'True'">True</EnableRegFreeCom>
   </PropertyGroup>
 
   <ItemGroup>
@@ -24,11 +30,40 @@
   </ItemGroup>
 
   <Target Name="ServerUsage"
+          Condition="'$(RegFree)' != 'True'"
           AfterTargets="Build">
     <Message Importance="High" Text="%0a************************************%0a*** $(MSBuildProjectName) usage instructions ***%0a************************************" />
     <Message Importance="High" Text="The server must be COM registered in order to activate.%0aThe following commands must be executed from an elevated command prompt." />
     <Message Importance="High" Text="Register:%0a    regsvr32.exe &quot;$(ProjectDir)$(OutputPath)$(ComHostFileName)&quot;" />
     <Message Importance="High" Text="Unregister:%0a    regsvr32.exe /u &quot;$(ProjectDir)$(OutputPath)$(ComHostFileName)&quot;" />
   </Target>
 
+  <Target Name="ServerUsage_RegFree"
+          Condition="'$(RegFree)' == 'True'"
+          AfterTargets="Build">
+    <Message Importance="High" Text="%0a************************************%0a*** $(MSBuildProjectName) usage instructions ***%0a************************************" />
+    <Message Importance="High" Text="A RegFree COM manifest has been created for the server.%0aThe manifest '@(RegFreeComManifest->'%(Filename)%(Extension)')' must be included during server deployment.%0aThe COMServer project will copy all required outputs to the COMClient output directory." />
+
+    <ItemGroup>
+      <ServerOutput Include="$(OutputPath)*.dll" />
+      <ServerOutput Include="$(OutputPath)*.runtimeconfig.json" />
+      <ServerOutput Include="$(OutputPath)*.deps.json" />
+      <ServerOutput Include="$(OutputPath)*.manifest" />
+    </ItemGroup>
+
+    <!-- Deploy all required server outputs -->
+    <Copy SourceFiles="@(ServerOutput)"
+          DestinationFolder="../COMClient/$(OutputPath)" />
+  </Target>
+
+  <Target Name="Clean_RegFree"
+          AfterTargets="Clean">
+    <ItemGroup>
+      <ServerOutputToDelete Include="../COMClient/$(OutputPath)COMServer.*" />
+    </ItemGroup>
+
+    <!-- Cleanup deployed server outputs -->
+    <Delete Files="@(ServerOutputToDelete)" />
+  </Target>
+
 </Project>

core/extensions/COMServerDemo/ReadMe.md

@@ -15,6 +15,8 @@ Build and Run
 
 The project will only build and run on the Windows platform.
 
+### Registered COM ###
+
 1) Install .NET Core 3.0 Preview 5 or later.
 
 1) Navigate to the root directory and run `dotnet.exe build`.
@@ -23,4 +25,20 @@ The project will only build and run on the Windows platform.
 
 1) Navigate to `COMClient/` and run `dotnet.exe run`.
 
+Program should output an estimated value of π.
+
 **Note** Remember to unregister the COM server when the demo is complete.
+
+### RegFree COM ###
+
+1) Install .NET Core 3.0 Preview 5 or later.
+
+1) Navigate to the root directory and run `dotnet.exe build /p:RegFree=True`.
+
+    - If the Registered COM demo was previously run, the project should be cleaned first - `dotnet.exe clean` 
+
+1) Run the generated binary directly e.g. `COMClient\bin\Debug\netcoreapp3.0\COMClient.exe`.
+
+Program should output an estimated value of π.
+
+**Note** The RegFree COM scenario requires a customized [application manifest](https://docs.microsoft.com/windows/desktop/sbscs/manifests) in the executing binary. This means that attempting to execute through `dotnet.exe` will not work and instead trigger a rebuild of the project.