Copied to clipboard

Flag this post as spam?

This post will be reported to the moderators as potential spam to be looked at


  • jake williamson 207 posts 872 karma points
    Jan 27, 2022 @ 05:12
    jake williamson
    1

    how to create an umbraco 9 plugin nuget package

    hey out there,

    ok, this is something we've been struggling with for a while: how can we create an umbraco 9 plugin nuget package?!

    we've read through the https://our.umbraco.com/documentation/Extending/Packages/Creating-a-Package/ and understand the process.

    however, this doesn't cover the main things that you'll encounter when wanting to package up a plugin, namely:

    1. the plugin has two projects in a solution, a 'core' project with the c# code and a 'editor' project which has all the angular files. so we need to generate two separate nuget packages
    2. how do we specify the dependencies? the package generated from the 'editor' project will have a version dependency on the 'core' project package using the same version
    3. how can we include files in the nuget package that aren't in the solution e.g. a 'read me' that opens after the package has been installed?
    4. there's no mention of a nuspec file but this could be the solution to the above points?!

    we've been digging around in a couple of v9 packages that would need to also solve the above and there doesn't seem to be any one clear way:

    https://github.com/leekelleher/umbraco-contentment/blob/dev/v3.x/build/build-pkgs.ps1 https://github.com/DanDiplo/Umbraco.GodMode/tree/v9/Diplo.GodMode/build https://github.com/KevinJump/uSync/tree/v9/main/dist https://github.com/skybrud/Skybrud.Umbraco.Redirects/tree/v3/main/src/build https://github.com/vendrhub/vendr-usync

    it's way confusing! and kinda frustrating... we've upgraded the bento plugin to version 9 (https://github.com/KOBENDigital/bento.editor) and're desperate to get it released...

    ...but as our v8 build scripts no longer work, we've hit a complete brick wall until we can create the nuget package...

    if anyone out there can point us in the right direction, it'd be amazing!

    as ever, any suggestions are greatly received ;)

  • Kevin Jump 2309 posts 14673 karma points MVP 7x c-trib
    Jan 27, 2022 @ 09:34
    Kevin Jump
    0

    Hi Jake,

    I can only talk about the way we do it (and you've seen from the uSync repo). We have moved to having the nuget packages built from the csproj files. which is why the powershell build script we have is mainly :

    dotnet pack .\pathto.csproj. 
    

    its a bit of a pain at first but we've found its just a little more consistant and easier to manage with the .csproj, and i can have a go at answering your points .

    1. We have multiple projects too, but really because we have other projects (such as uSync.Complete) that only want to consume the dll's from our project. If you don't think that then you could munge it into one package .

    however - we do the following :

    • uSync.BackOffice (the dll's to run usync)
    • uSync.BackOfficeAssets (the app_plugins stuff) (has a targets file! see below)

    then we have an almost empty project called uSync. and that is the nuget package that most people see.

    1. Dependencies The above project structure manages our dependencies for us,. so the uSync project has a dependency on the uSync.BackOffice and uSync.BackOffice.StaticAssets projects. when you dotnet pack them all, dependencies managed and the versions move up with each other (e.g if we dotnet pack v10.1 then the dependencies on the other projects in the same solution will all be v10.1)

    Dependencies on Umbraco come from us having the dependencies on the umbraco packages inside our projects (so for example i think its Umbraco.Cms.BackOffice in uSync's case)

    1. You can add extra files in the csproj file : so in uSync.csproj we have:

      <ItemGroup>
         <None Include="readme.md" Pack="true" PackagePath="\" />
        <None Include="readme.txt" Pack="true" PackagePath="\" />
        <None Include="usync-logo.png" Pack="true" PackagePath="\" />
      </ItemGroup>
      

    but be aware these readme's don't get shown all the time, if someone does a dotnet add package or adds the reference in their own csproj file this won't cause the readme to open anywhere.

    1. Nuspec We did start our v9 packages with nuspecs but moved to the .csproj mainly for the ease or maintenance and it was a simpler build / versioning process for us.

    note about .targets files

    For all methods (*.csproj or .nuspec) you will need to have a {project}.targets file that copies the contents of App_Plugins over from the package into the developers Umbraco package. this is an unfortunate netcore thing at the moment as it doesn't work the old framework way where content is automatically included in the project when the package is installed.

    we do this fairly simply in the uSync.BackOffice.StaticAssets project (https://github.com/KevinJump/uSync/tree/v9/main/uSync.Backoffice.Assets) but i would say is check the version of the targets file that gets generated when you do a dotnet new umbracopackage command as this is probibly the cleanest starting point.

    things to note about .target files

    1. they must have the same name as your nuget package . e.g if your package id is mysuperpackage your targets file needs to be mysuperpackage.targets.

    2. they should to be included in the nuget file in buildTransitive folder

    e.g in the csproj file. you have something like this :

    <None Include="build\**\*.*">
        <Pack>True</Pack>
       <PackagePath>buildTransitive</PackagePath>
    </None>
    
    1. the copy happens when the user builds or runs the site (so dotnet build/dotnet run). not when they install the package, so don't expect your app_plugins files to appear right away.

    2. the app_plugins files get overwritten every build/run so don't put anything in there you expect the users to have to edit and those changes can get lost

    merging two projects into one nuspec

    If you want to It should be possible to include all of your dlls and assets into a single project from two projects. but i think it will involve a little bit of digging.

    . At the simplest level you could have something copy the web files into a folder in the dll project and then include them in the package using something like

    <Content Include="App_Plugins\MyPlugin\**\*.*">
         <ExcludeFromSingleFile>true</ExcludeFromSingleFile>
         <CopyToPublishDirectory>Always</CopyToPublishDirectory>
    </Content>
    

    . the 'Proper' way probably involves doing something special to the project dependency line to include the dll of the dependent project in the parent package files.

     <!-- so there is probably something you can add to a line like this to mean the nuspec file for the project using this will also include the project dll -->
     <ProjectReference Include="..\uSync.BackOffice\uSync.BackOffice.csproj" />
    

    but to be honest this is something i think you would need to lookup.

  • jake williamson 207 posts 872 karma points
    Jan 27, 2022 @ 22:25
    jake williamson
    0

    hi kevin,

    can't thank you enough for the info and detailed explanation, really appreciate you putting it together.

    the bento v9 upgrade is 99.9% complete and packaging it up was the 0.1% that was proving to be the trickiest part - the above will really help us to hopefully get it wrapped up and ready for release.

    we'll put it into action and report back!

    cheers,

    jake

  • Angelo 111 posts 260 karma points
    Aug 26, 2022 @ 12:12
    Angelo
    0

    Hello Jake

    i have the same problem ...and i have also several plugins inside my App_Plugins folder that i want to include then in one unique package

    did you solve your problem ?

Please Sign in or register to post replies

Write your reply to:

Draft