2f7789b374
WHAT / WHY
----------
GetPackageManifestRequestHandler previously identified a loaded plugin's
NuGet PackageId by fuzzy-matching AssemblyTitle/AssemblyName against the
config's packageId - a chain that silently fails for any plugin whose
AssemblyTitle/AssemblyName doesn't happen to match its PackageId (verified
against real shipped plugin DLLs; see FINDINGS-nuget-packageid-gaps.md).
epi-symetrix-dsp and epi-shure-mxa have already backported a
Directory.Build.props change that embeds
`<AssemblyMetadata Include="PackageId" Value="$(PackageId)" />`, giving
Essentials an unambiguous, authoritative PackageId via
AssemblyMetadataAttribute("PackageId", ...) instead of guessing. Validated
by building both plugins and inspecting the generated AssemblyInfo.cs.
Changes:
- src/Directory.Build.props: add the same AssemblyMetadata PackageId item,
so every Essentials-owned assembly (Core, Essentials, Devices.Common,
MobileControl, MobileControl.Messengers) now embeds its real PackageId
too - previously none of them did.
- GetPackageManifestRequestHandler.cs:
- PopulatePackages: read AssemblyMetadataAttribute("PackageId", ...) from
loaded plugin assemblies and use it as the first-priority match/identity
signal, ahead of the AssemblyTitle -> AssemblyName -> AssemblyName-minus-
".4Series" fallback chain. Loaded-but-unconfigured plugins that carry
this metadata now report a PackageId in the manifest instead of null.
- PopulateEssentials: replace the hardcoded "PepperDash.Essentials"
fallback (which matched none of the real PackageIds) with the reflected
value from PepperDash.Essentials.Core's own assembly metadata.
Fully backward compatible: plugins without the updated Directory.Build.props
(most existing epi-* repos today) fall through to the prior fallback chain
unchanged.
RECOMMENDATIONS - Essentials & sub-projects (this repo)
--------------------------------------------------------
- AssemblyName/AssemblyTitle drift from PackageId across sub-projects
(confirmed via generated AssemblyInfo.cs, not assumed):
PepperDash.Essentials.Core: PackageId "PepperDash.Essentials.Core"
vs AssemblyName "PepperDash_Essentials_Core"
PepperDash.Essentials.Devices.Common: PackageId "PepperDash.Essentials.Devices.Common"
vs AssemblyName "Essentials Devices Common"
PepperDash.Essentials.MobileControl: PackageId "PepperDash.Essentials.MobileControl"
vs AssemblyName "epi-essentials-mobile-control"
PepperDash.Essentials.MobileControl.Messengers: PackageId "...Messengers"
vs AssemblyName "mobile-control-messengers"
Only PepperDash.Essentials and PepperDash.Core happen to agree. Fixing
AssemblyName changes the physical .dll filename for existing consumers,
so this needs a deliberate, versioned decision - not bundled here.
- Once this ships and bakes for a release or two, consider deleting the
now-redundant "PepperDash.Essentials" hardcoded string entirely and the
Product/AssemblyTitle-based Name fallback, since AssemblyMetadata PackageId
supersedes both for any assembly built after this change.
RECOMMENDATIONS - EPI plugin repos (epi-*)
-------------------------------------------
- Backport `<AssemblyMetadata Include="PackageId" Value="$(PackageId)" />`
into every existing epi-* repo's src/Directory.Build.props (recommendation
E from FINDINGS-nuget-packageid-gaps.md). This is opt-in and additive -
repos that skip it keep working via the existing fallback chain, but gain
nothing until they backport it and cut a new release.
- Land the corresponding fix in EssentialsPluginTemplate
(src/Directory.Build.props + src/epi-make-model.4Series.csproj) so all
*new* plugin repos get this by default, and fix the template's own
AssemblyTitle/PackageId drift ("Plugin" vs "Plugins") while there.
- Already-published plugin versions can't be retroactively fixed - this only
takes effect on a plugin's next release after adopting the template change.
WORKFLOW RECOMMENDATIONS
-------------------------
- Extend workflow-templates' essentialsplugins-4Series-builds.yml "Check
Package Name" step to validate the built DLL's embedded
AssemblyMetadataAttribute("PackageId", ...) (and/or AssemblyTitle as a
fallback) against the repo-derived expected package name - today it only
compares the .nupkg filename, which would not have caught drift like
epi-display-samsung-mdc's AssemblyTitle mismatch.
- Sequence this after the template + per-repo backports have landed and
baked for a release cycle, otherwise it will fail CI for every epi-*
repo that hasn't picked up the Directory.Build.props change yet. Gate it
behind the existing bypassPackageCheck input for repos not yet ready.
|
||
|---|---|---|
| .config | ||
| .github | ||
| .vscode | ||
| docs | ||
| IR Drivers | ||
| Sample Presets | ||
| src | ||
| .gitignore | ||
| .gitmodules | ||
| .releaserc.json | ||
| CONTRIBUTING.md | ||
| Crestron-Library-Usage-Analysis.md | ||
| LICENSE.md | ||
| PepperDash.Essentials.4Series.sln | ||
| README.md | ||
PepperDash Essentials Framework (c) 2020
Latest Release
License
Provided under MIT license
Overview
PepperDash Essentials is an open source Crestron framework that can be configured as a standalone program capable of running a wide variety of system designs and can also be utilized as a plug-in architecture to augment other Simpl# Pro and Simpl Windows programs.
Essentials Framework is a collection of C# / Simpl# Pro libraries that can be utilized in several different manners. It is currently operating as a 100% configuration-driven system, and can be extended to add different workflows and behaviors, either through the addition of further device "types" or via the plug-in mechanism. The framework is a collection of "things" that are all related and interconnected, but in general do not have dependencies on each other.
Minimum Requirements
- Essentials Framework runs on any Crestron 3-series processor, 4-series processor or Crestron's VC-4 platform.
- To edit and compile the source, Microsoft Visual Studio 2008 Professional with SP1 is required.
- Crestron's Simpl# Plugin is also required (must be obtained from Crestron).
Dependencies
The PepperDash.Core SIMPL# library is required. It is referenced via nuget. You must have nuget.exe installed and in the PATH environment variable to use the following command. Nuget.exe is available at nuget.org.
Installing Dependencies
To install dependencies once nuget.exe is installed, run the following command:
nuget install .\packages.config -OutputDirectory .\packages -excludeVersion.
To verify that the packages installed correctly, open Essentials and make sure that all references are found, then try and build it.
Installing Different versions of PepperDash Core
If you need a different version of PepperDash Core, use the command nuget install .\packages.config -OutputDirectory .\packages -excludeVersion -Version {versionToGet}. Omitting the -Version option will pull the version indicated in the packages.config file.
Utilization
Essentials was originally conceptualized as a standalone application for running control system logic entirely in Simpl# Pro. It is primarily designed around accomplishing this goal, but during development, it became obvious that it could easily be leveraged to also serve as a partner application to one or more SIMPL Windows programs.
Utilization of Essentials Framework falls into the following categories:
-
Standalone Control System Application for controlling one or more rooms. See Standalone Use
-
Partner Application to a SIMPL Windows program. This allows for several useful advantages. See SIMPL Windows Bridging
-
Dynamic device instantiation. Devices can be defined in configuration and instantiated at runtime and then bridged to a SIMPL Windows program via EISC.
-
Advanced logic. Some logic operations that cannot be affectively accomplished in SIMPL Windows (ex. JSON/XML serialization/deserialization, database operations, etc.) can be done in the Simpl# Pro environment and the necessary input and output bridged to a SIMPL Windows program via EISC.
- Hybrid Application that may contain elements of both standalone control and SIMPL partner application integration.
- There may be a use case where a device can only be defined in a single application, but that device may need to be interacted with from multiple applications. The device can be defined in an Essentials application, interacted with in that application and also bridged to one or more SIMPL Windows applications.
Documentation
For detailed documentation, see the Wiki.
Support
- Check out our Discord Server
How-To (Getting Started)
See Getting Started