pepperdash / essentialsplugintemplate Goto Github PK

A template plugin meant to be used as a starting point for a new plugin. Fork as necessary

License: MIT License

C# 99.75% Batchfile 0.25%

essentialsplugintemplate's Introduction

Essentials Plugin Template (c) 2023

Overview

Fork this repo when creating a new plugin for Essentials. For more information about plugins, refer to the Essentials Wiki Plugins article.

This repo contains example classes for the three main categories of devices:

EssentialsPluginTemplateDevice: Used for most third party devices which require communication over a streaming mechanism such as a Com port, TCP/SSh/UDP socket, CEC, etc
EssentialsPluginTemplateLogicDevice: Used for devices that contain logic, but don't require any communication with third parties outside the program
EssentialsPluginTemplateCrestronDevice: Used for devices that represent a piece of Crestron hardware

There are matching factory classes for each of the three categories of devices. The EssentialsPluginTemplateConfigObject should be used as a template and modified for any of the categories of device. Same goes for the EssentialsPluginTemplateBridgeJoinMap.

This also illustrates how a plugin can contain multiple devices.

Cloning Instructions

After forking this repository into your own GitHub space, you can create a new repository using this one as the template. Then you must install the necessary dependencies as indicated below.

Dependencies

The Essentials libraries are required. They 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 from the root directory of your repository: nuget install .\packages.config -OutputDirectory .\packages -excludeVersion. Alternatively, you can simply run the GetPackages.bat file. To verify that the packages installed correctly, open the plugin solution in your repo 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.

Instructions for Renaming Solution and Files

See the Task List in Visual Studio for a guide on how to start using the template. There is extensive inline documentation and examples as well.

For renaming instructions in particular, see the XML remarks tags on class definitions

Build Instructions (PepperDash Internal)

Generating Nuget Package

In the solution folder is a file named "PDT.EssentialsPluginTemplate.nuspec"

Rename the file to match your plugin solution name
Edit the file to include your project specifics including
1. PepperDash.Essentials.Plugin.MakeModel Convention is to use the prefix "PepperDash.Essentials.Plugin" and include the MakeModel of the device.
2. https://github.com/PepperDash/EssentialsPluginTemplate Change to your url to the project repo

There is no longer a requirement to adjust workflow files for nuget generation for private and public repositories. This is now handled automatically in the workflow.

If you do not make these changes to the nuspec file, the project will not generate a nuget package

essentialsplugintemplate's People

Contributors

Stargazers

Watchers

Forkers

rbsystems norgate-av tdogny willis1776 derek555 logic-masters jonavila ndorin batourin os-rsingleton radusimon84 lou-iiacovelli jakewwoods ciasia mnchartier jaredambrosegse jonnyarndt

essentialsplugintemplate's Issues

[FEATURE]-Update to latest plugin loading mechanism and rename master branch to main

Is your feature request related to a problem? Please describe.
Needs to be updated to use latest plugin loading mechanisms

[BUG]-PluginTemplate-OutOfDate

Describe the bug
The plugin template, specifically the github workflows, are out of date.

[FEATURE]-Update Template Solution and Project naming

Is your feature request related to a problem? Please describe.
Update solution and project naming in the template to document and identify the naming standards for creating new plugins.

[FEATURE]-Update actions to versions that run Node 16

GH is deprecating/removing Node 12 from the action runners sometime next summer. Most of the default actions we use have been updated to run on Node 16, but that necessitates changing all of the workflow files to use the latest versions.

In order to prevent issues, workflows should be updated to use the following versions:
actions/checkout@v2 -> actions/checkout@v3
actions/upload-artifact@v1 -> actions/upload-artifact@v3
actions/download-artifact@v1 -> actions/download-artifact@v3

fleskesvor/create-release seems to have disappeared, and actions/upload-release-asset is archived and not maintained by Github anymore. Some research and testing will be necessary to determine what suggested actions should replace them.

Also, Actions now supports job outputs. It might be a good idea to use them to get the version number out of the build job to the publish job instead of writing the version number to a text file.

[FEATURE]-Automatically set GH nuget repo path for packages

Is your feature request related to a problem? Please describe.
As template repos can be used across orgs to create repos, it makes sense to automate this. The repository owner is available in a workflow under the github.repository_owner value. This can be used to build the nuget registry URL for packages. The owner in the .nuspec file does have to match the org, so that change should be added to the docs/steps for creating a repo from this template.

It might be worth it to look at the GH Docs and see what other values can be pulled from context and used to make improvements to the workflows.

https://docs.github.com/en/actions/learn-github-actions/contexts#github-context

[FEATURE]-Update factory and device template to allow for devices that consume IBasicCommunication as well as those that don't

Is your feature request related to a problem? Please describe.
The template assumes that the device will communicated via IBasicCommunication. There are many instances where a device may be virtual or just some logic contained as a device and either not communicate or do so by some other means than IBasicCommunication supports.

Describe the solution you'd like
Add better examples and scenarios in the BuildDevice factory method to handle different scenarios. Update the device template to better illustrate how to appropriately construct the device based on those scenarios.

[FEATURE]-Automate-Initial-Plugin-Creation

Is your feature request related to a problem? Please describe.
Individuals often go long periods of time before generating a new plugin. In some of that plugin development drought, it would become possible for either the actions required to change a template to be modified, or the developer simply doesn't know the process, or doesn't realize a process exists. In absence of documentation, which isn't always up to date, we should be able to script the initial solution generation process.

Describe the solution you'd like
A combination of locally-available powershell scripts and/or build actions to modify a recently-cloned solution file to adhere to internal naming conventions while being descriptive of the solution presented, along with automatically generating or editing a properly-formatted, internally-compliant nuspec file for nuget publishing.

Describe alternatives you've considered
The current solutions are entirely manual and frought with the possibility of human error or simple forgetfulness

Additional context
This isn't highly urgent, but I want to open a discussion about this. I strongly encourage you to share your thoughts on this issue.