EssentialsPluginTemplate/Readme-Upgrade-to-4Series.md

Upgrading an EPI: Essentials v1.x → v2.x

Preparation

1. Clone the Template Repo referred to as TR to your local machine.
   • EssentialsPluginTemplate
2. Checkout main branch in the TR.

Branching

4. In your EPI repo:
   • Confirm it does not already support Essentials v2.x.
   • Ensure there is no existing 4-series update branch.
   • Create a new branch (e.g., feature/4-series-updates) from main.

Upgrade Steps

5. In the new branch:

   • Replace EPI .github files/folders with those from TR as needed.
     • Note: Retain any custom workflows if required. Consult with PepperDash Team if unsure.
   • Copy the following from TR to EPI:
     • .releaserc.json (root)
     • epi-make-model.4Series.sln (root)
     • src/epi-make-model.4Series.csproj (create src folder if missing)
     • images folder (if your readme.md lacks the standard logo)
   • Initial Commit: Commit changes, but do not push yet.

6. If EPI has a src/*.nuspec file:

   • Record these values from Nuspec for later:
     • <id> (Package ID)
     • <projectUrl> (Project URL)
     • <title> (Assembly Title)

7. Open Solution:

   • Open epi-make-model.4Series.sln in Visual Studio 2022.
   • If errors occur, ensure the .csproj file is located within src folder.

8. Update Project Properties:

   • In src/epi-make-model.4Series.csproj, update:

     • AssemblyTitle (from nuspec <title>)
     • RootNamespace (from existing EPI, device namespace actual)
     • PackageProjectUrl (from nuspec <projectUrl>)

   • Rename make-model build path references shown below:

     

   • Add runtime exclusion:
     Add <ExcludeAssets>runtime</ExcludeAssets> to the PepperDash Essentials PackageReference.

     

9. Copy Build Files:

   • Copy src/Directory.Build.props and src/Directory.Build.targets from TR.
   • Update RepositoryUrl in Directory.Build.props to match nuspec PackageProjectUrl.
   • Remove "template" text from <Product> in Directory.Build.props as needed.

10. Clean Up:

    • Delete old Visual Studio 2008 files: .sln, .suo, .nuspec, .csproj, .csproj.user, .projectinfo.
    • Ensure file structure matches below example:

  ├── src/
  │   ├── Directory.Build.props
  │   ├── Directory.Build.tagets
  │   ├── *.3Series.csproj
  │   └── *.4Series.csproj
  ├── .releaserc.json
  ├── *.3Series.sln
  ├── *.4Series.sln
  ├── LICENSE.md
  └── README.md

11. Rename Solution/Project as needed.

    

12. Update Project References and Dependencies

    • Remove old PepperDash Essentials dependency.
    • Add PepperDash Essentials v2.x dependency via Visual Studio 2022 > Project > Manage Nuget Packages.

    

13. Update Factory Class:
    Set MinimumEssentialsFrameworkVersion to match the Essentials version dependency.

14. Build Solution:
    Ensure solution compiles (warnings about obsolete Debug.Console calls are OK).

15. Update Debug Calls:
    Replace Debug.Console with Debug.Log methods as appropriate (see table).

    

Completion Checklist

• EPI compiles with no warnings.
• Obsolete methods updated to modern equivalents.
• Workflows complete successfully; packages generated via GitHub and NuGet.org.
• readme.md includes:
  • Usage/setup instructions
  • Example SIMPL Windows bridge joinmap
  • Example device communication structure/properties
• EPI tested against full release Essentials version.
• EPI tested by another developer.
• Full release of EPI.

---

For questions about workflows or customizations, consult with PepperDash Team.