feat!: migrate plugin to Essentials v3 (net8)

[anthony-lopez-pd]

Summary

Migrate PepperDash.Essentials.DM plugin from Essentials v2 (net472) to Essentials v3 (net8).

Changes

Project Configuration

• Update TargetFramework from net472 to net8
• Update PepperDashEssentials NuGet from 2.7.0 to 3.0.0-dev-v3-testing.13
• Remove obsolete framework references
• Bump version to 3.0.0-local

Breaking API Fixes

• Change CustomActivate() from public to protected override in 11 device classes
• Replace eRoutingSignalType.UsbInput/UsbOutput with eRoutingSignalType.Usb
• Replace eRoutingSignalType.SecondaryAudio with eRoutingSignalType.AudioVideo
• Add IKeyName/IKeyed implementation to DmpsAudioOutput and DmCardAudioOutputController

Bug Fixes

• fix: KeyNotFoundException in LinkHdmiInputToApi (resolves fix: KeyNotFoundException in LinkHdmiInputToApi when inputSlotSupportsHdcp2 config is incomplete #33) — Direct dictionary access on PropertiesConfig.InputSlotSupportsHdcp2[ioSlot] threw when config entries were missing for HDMI input slots. Replaced with TryGetValue (defaulting to false), consistent with the pattern already used in LinkBasicTxToApi. Added ContainsKey guard for InputCardHdcpStateFeedbacks.

New Feature: HD-MD-NxM-4KZ-E Switcher Support (938e842)

• New HdMdNxM4kzEController — Standalone bridgeable controller for the 4KZ-E switcher family, implementing IRoutingNumericWithFeedback and IHasFeedback
• Supported models: HdMd4x14kzE, HdMd4x24kzE, HdMd4x44kzE, HdMd8x44kzE, HdMd8x84kzE (factory type names: hdmd4x14kze, hdmd4x24kze, hdmd4x44kze, hdmd8x44kze, hdmd8x84kze)
• Key design decision: New standalone class rather than modifying existing HdMdNxM4kEBridgeableController — the 4KZ-E models have a different Crestron SDK type hierarchy (HdMdNxM4kzE base vs HdMdNxM), different constructors (2-arg, no IP address), and different input/output types (HdMdNxM4kzEHdmiInput/HdMdNxM4kzEHdmiOutput)
• Fixes feedback bug from previous add-hdmdNxM4kze-support branch where switching worked but feedback didn't — root cause was casting to wrong types (HdMdNxMHdmiInput instead of HdMdNxM4kzEHdmiInput)
• New HdMdNxM4kzEPropertiesConfig config class with Control, Inputs, Outputs properties
• Reuses existing HdMdNxM4kEControllerJoinMap from Essentials Core
• Feedbacks: VideoInputSync, VideoOutputRoute, InputName, OutputName, OutputRouteName, InputHdcpEnable, DeviceName, AutoRoute
• Tests updated: Factory count 12→13, 5 new type name metadata tests, config deserialization tests (84 total tests passing)

Code Cleanup

• Remove unused Crestron.SimplSharp.Reflection import
• Replace Debug.Console with Debug.LogInformation
• Update MinimumEssentialsFrameworkVersion to 3.0.0 in all factories (now 13 total)

Testing Checklist

• Solution builds without errors targeting net8
• CPLZ package generates correctly
• Zero remaining Debug.Console calls (except 3 commented-out)
• Zero SERIES3/SERIES4 references
• Zero SimplSharp.Reflection references
• All MinimumEssentialsFrameworkVersion set to 3.0.0
• Plugin loads in Essentials v3 runtime on RMC4
• DM-MD-8x8 chassis registers successfully (IP-ID 0x80)
• EISC bridge links all 28 join attributes without error
• Video/audio routing confirmed (Input 6→Out 1, Input 3→Out 5, Input 6→Out 2)
• Resolution feedback working (Input 1: 1920x1080@60Hz)
• HDCP events firing on all applicable inputs
• AudioBreakaway/USBBreakaway feedback operational
• All 84 unit tests pass (0 failed, 0 skipped)
• HD-MD-NxM-4KZ-E hardware deployment validation

BREAKING CHANGE: Plugin now targets net8 and requires Essentials v3. Not compatible with Essentials v2 (net472) runtime.

[ndorin]

@anthony-lopez-pd this looks great so far! I approved but see it's still marked as draft. Let me know when it's ready for review.

[anthony-lopez-pd]

@copilot review please

[Copilot]

@copilot review please

Review done. Found and fixed the following issues in commits ed96527 and 63b5253:

Bugs fixed:

1. USB output routing regression (DmChassisController.ExecuteNumericSwitch): The v3 migration collapsed eRoutingSignalType.UsbInput/UsbOutput into a single Usb flag, making the USB Output branch unreachable dead code. The OutputUsb bridge join was silently routing to Chassis.Inputs[slot] instead of Chassis.Outputs[slot]. Extracted the output-side logic into a new ExecuteUsbOutputSwitch private method and wired the OutputUsb join to it.

2. KeyNotFoundException in InputCardHdcpStateFeedbacks lambda (DmChassisController): Three PropertiesConfig.InputSlotSupportsHdcp2[slot] direct accesses were inside a try/catch that only caught InvalidOperationException — KeyNotFoundException would propagate uncaught. Replaced with TryGetValue (defaulting to false) matching the fix already applied to LinkHdmiInputToApi.

Code quality:

• Removed the redundant duplicate eRoutingSignalType.Usb check in DmpsRoutingController.sigTypeIsUsbOrVideo (copy-paste artefact from the UsbInput→Usb + UsbOutput→Usb migration).
• Replaced the now-identical isUsbInput/isUsbOutput variable pair in ExecuteSwitch with a single isUsb variable.
• Extracted the 8×8 USB output slot offset magic number 16 into a named constant Usb8x8OutputSlotOffset.

All 84 unit tests continue to pass; CodeQL scan found 0 alerts.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• crl.entrust.net
  • Triggering command: /usr/bin/dotnet dotnet build src/PepperDash.Essentials.DM.csproj --configuration Debug 10]: print(f'{run["id"]} | {run["name"]} | {run["status"]} | {run["conclusion"]} | {run["head_branch"]}') (dns block)
  • Triggering command: /usr/bin/dotnet dotnet restore --no-dependencies /home/REDACTED/work/PepperDash.Essentials.DM/PepperDash.Essentials.DM/PepperDash.Essentials.DM.4Series.sln --packages /tmp/codeql-scratch-f42d22a4692b36ae/dbs/csharp/working/packages /p:DisableImplicitNuGetFallbackFolder=true --verbosity normal /p:TargetFrameworkRootPath=/tmp/codeql-scratch-f42d22a4692b36ae/dbs/csharp/working/emptyFakeDotnetRoot /p:NetCoreTargetingPackRoot=/tmp/codeql-scratch-f42d22a4692b36ae/dbs/csharp/working/emptyFakeDotnetRoot /p:AllowMissingPrunePackageData=true (dns block)
• ocsp.entrust.net
  • Triggering command: /usr/bin/dotnet dotnet build src/PepperDash.Essentials.DM.csproj --configuration Debug 10]: print(f'{run["id"]} | {run["name"]} | {run["status"]} | {run["conclusion"]} | {run["head_branch"]}') (dns block)
  • Triggering command: /usr/bin/dotnet dotnet restore --no-dependencies /home/REDACTED/work/PepperDash.Essentials.DM/PepperDash.Essentials.DM/PepperDash.Essentials.DM.4Series.sln --packages /tmp/codeql-scratch-f42d22a4692b36ae/dbs/csharp/working/packages /p:DisableImplicitNuGetFallbackFolder=true --verbosity normal /p:TargetFrameworkRootPath=/tmp/codeql-scratch-f42d22a4692b36ae/dbs/csharp/working/emptyFakeDotnetRoot /p:NetCoreTargetingPackRoot=/tmp/codeql-scratch-f42d22a4692b36ae/dbs/csharp/working/emptyFakeDotnetRoot /p:AllowMissingPrunePackageData=true (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)