Merge pull request #488 from microsoft/pete-dev

Update dev docs

docs/developer-how-to/how-to-install-development-builds.md

@@ -0,0 +1,72 @@
+---
+layout: page
+title: How to Install Development Builds
+parent: Developer How-to
+has_children: false
+---
+
+# How to Install Development Service builds
+
+Windows MIDI Services has been designed from the start to be expandible with new transports, and in the future, with new transforms, by the developer community, all without having to write kernel drivers. These components are delivered as COM DLLs implementing specific interfaces, and then registered on the local computer.
+
+## Evaluate if you need to do this
+
+If you are a regular musician, we generally recommend you stick with what is installed in-box in Windows. If, however, you are technically astute, and safe in your computer practices, you can unlock Windows MIDI Services to enable in-development service plugins to be installed, and service settings to be changed.
+
+> Note: The steps in this file will eventually be replaced by developer-mode settings in the MIDI Settings app.
+
+## Install PowerShell 7
+
+The scripts require PowerShell 7 or newer. You can install PowerShell [following these instructions](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows).
+
+After installing PowerShell, you need to enable script execution in the Windows Settings app: Settings > System > For Developers > PowerShell.
+
+![Enable PowerShell Scripts in Settings](.\enable-powershell-scripts.png)
+
+## Take Ownership of the Registry Keys
+
+When Windows MIDI Services is included with the in-box install of Windows, the registry keys for the transport plugins and other MIDI Services settings are all protected, and owned by Trusted Installer. This helps prevent malicious apps from adding entries and loading any arbitrary code into the service.
+
+Developers and those using preview versions of plugins, however, need to be able to write to those keys to add new transports, or change developer settings.
+
+Each developer release comes with a zip file with two PowerShell scripts and two .cmd files which launch them. The first lists the registry entries for for all the COM components used by the service, as well as the service itself. The second, when run as administrator, will take ownership of the relevant keys allowing the values to be replaced with development versions of components. We recommend this be done only by developers and other more technical users.
+
+Run the two .cmd files from a normal developer command prompt (cmd, not PowerShell), as Administator as follows.
+
+### List Registry State
+
+First, run `list-reg.cmd` to see the current registry values. In-box services and components are all installed in `\Windows\System32`. The pre-release versions of those components are installed in `\Program Files\Windows MIDI Services`
+
+```
+c:\foo\bar> list-reg.cmd
+```
+
+![Before](.\list-reg-before.png)
+
+You can see in this that we have the stock plugins listed as running from `System32`, and no entry for the Network MIDI 2.0 plugin. This is expected for the time when I wrote this article, as Network MIDI 2.0 is/was an in-development preview plugin, not an in-box plugin.
+
+### Prepare for a Developer Install
+
+After validating your current state is the in-box state (this is reverted to this state with each Windows Upgrade, including Insider Builds, as well as with any Windows MIDI Services update), you'll next want to take ownership of the keys.
+
+Run the `dev-prep.cmd` file from an Administrator command prompt (again, a regular command shell, not PowerShell).
+
+![Developer Prep Script](.\dev-prep-output.png)
+
+If you see any errors in the output, stop at this point and investigate. Otherwise, the installers will appear to run fine, but if they do not have permissions to write to the correct registry keys, you won't be using the components you just installed.
+
+## Install the Developer Packages
+
+Now you may install all of the developer packages via their installers.
+
+## Verify the Installation
+
+Finally, run the `list-reg.cmd` file again to verify that everything is installed in the new locations.
+
+![After](.\list-reg-after.png)
+
+If everything worked, you'll see the files reported as being from `Program Files` instead of `System32`. You are now running the preview versions of the service and components.
+
+In some cases, you may want to leave the existing service, but install only a preview plugin. In that case, the service and other components will still show `System32`, but the new component will show `Program Files` as the location.
+
+> Note: These scripts only know about the plugins we've developed. Additional third-party components will not be shown in the output unless we know about and add them.

src/api/Service/Exe/MidiEndpointProtocolWorker.cpp

@@ -230,21 +230,6 @@ CMidiEndpointProtocolWorker::Start(
 
         m_alreadyTriedToNegotiationOnce = false;
 
-
-        // Partner device-compatibility requirement. May be able to remove this in the future
-        // but needed for now for their USB device to work properly. Given when this is called, 
-        // and that it is on a worker thread, it doesn't really negatively impact any other 
-        // devices or initial enumeration.
-        // Search for "#midisrv#midiu_ks_" is to restrict this to just USB devices using the 
-        // USB MIDI 2.0 driver, so network and other MIDI 2.0 transports are unaffected
-        if (auto index = internal::NormalizeEndpointInterfaceIdWStringCopy(m_endpointDeviceInterfaceId).find(L"#midisrv#midiu_ks_");
-            index != std::wstring::npos)
-        {
-            Sleep(2500);
-        }
-        // End partner compatibility mitigation added 2024-10-08
-
-
         TraceLoggingWrite(
             MidiSrvTelemetryProvider::Provider(),
             MIDI_TRACE_EVENT_INFO,

src/dev-tools/reg-helpers/dev-prep.cmd

@@ -6,6 +6,11 @@ echo can find this in Settings - System - For Developers - Powershell
 echo[
 echo You also need to run this from an elevated command prompt. Do not just double
 echo click this cmd file.
+echo[
+echo This must be run from a normal Windows command shell. If you are running
+echo PowerShell as your shell, please run the individual commands:
+echo     Unblock-File .\midi-pre-install-reg-steps.ps1
+echo     .\midi-pre-install-reg-steps.ps1
 echo ==================================================================================
 echo[
 pwsh -Command Unblock-File .\midi-pre-install-reg-steps.ps1

src/dev-tools/reg-helpers/list-reg.cmd

@@ -6,6 +6,11 @@ echo can find this in Settings - System - For Developers - Powershell
 echo[
 echo You also need to run this from an elevated command prompt. Do not just double
 echo click this cmd file.
+echo[
+echo This must be run from a normal Windows command shell. If you are running
+echo PowerShell as your shell, please run the individual commands:
+echo     Unblock-File .\midi-list-reg.ps1
+echo     .\midi-list-reg.ps1
 echo ==================================================================================
 echo[