Creating Umbraco Packages: Week 9

Creating Umbraco Packages: Week 9

Hello all!

Wow, it is week 9 already. The weeks are flying past. Before I know it, I'll be blogging about this topic for a year! But let's get started with this week's blog post.

Documentation

This week I've been focusing on writing the documentation for uSeoToolkit. Most of the general stuff is already done like installation, getting started and a few advanced topics like extending the packages. I am sure that there are still a few more topics to cover, but this should serve as a nice start for the documentation. I've also been wondering if I should make a video of the "getting started" part as that might also help people as it would be a lot more visual. I think uMarketingSuite also does this, so I wonder what method has the preference there.

But I also want to talk about Github Wiki. Last week I said that I would use Github Wiki for all the documentation, but having worked with it for a week now, I know that I have to use something else. Github Wiki feels so limited for an actual wiki. Every page is added to the sidebar instead of just having general navigation and having pages linked to each other. You can't even put images in like you would in issues or pull requests, it's crazy! The only way of adding images is to host them somewhere else and then embed them on the page. That is why I don't have any images on my documentation yet!

So, I'll be looking at some other ways of documentation. I think it would probably be best to combine them with a general website about uSeoToolkit. Something that I still have to build.

Pipelines

And then some stuff about pipelines! I want to be able to easily run a build pipeline to build my NuGet packages and send them off to the NuGet server. I don't want to do this manually as it'll just take a lot of time each time. I can just set up the build pipeline once and be done with it. For this, I'll be using Github actions. I've also used them for SimpleRedirects on Umbraco v9 and they work quite well. It is a bit different from the Azure Devops build pipelines as everything on Actions has to be done in a .yml file without a nice editor, but it is doable.

This is the pipeline that I am currently using for the sitemap package:

name: Sitemap Package Release

env:
  OUTPUT: ./Output
  CONFIG: Release

on:
  workflow_dispatch:
    inputs:
      package_version:
        description: 'Package version'
        required: true

jobs:
  build:

    runs-on: windows-latest

    steps:      
    - uses: actions/checkout@v2  

    - name: Setup .net core
      uses: actions/setup-dotnet@v1.4.0

    - name: Restore dependencies
      run: dotnet restore ./src/uSeoToolkit.Umbraco.Sitemap/uSeoToolkit.Umbraco.Sitemap.csproj

    - name: Restore dependencies
      run: dotnet restore ./src/uSeoToolkit.Umbraco.Sitemap.Core/uSeoToolkit.Umbraco.Sitemap.Core.csproj

    - name: Build
      run: dotnet build ./src/uSeoToolkit.Umbraco.Sitemap.Core/uSeoToolkit.Umbraco.Sitemap.Core.csproj --configuration ${{ env.CONFIG }} --no-restore

    - name: Build
      run: dotnet build ./src/uSeoToolkit.Umbraco.Sitemap/uSeoToolkit.Umbraco.Sitemap.csproj --configuration ${{ env.CONFIG }} --no-restore

    - name: Create NuGet package file for Core
      run: dotnet pack ./src/uSeoToolkit.Umbraco.Sitemap.Core/uSeoToolkit.Umbraco.Sitemap.Core.csproj -c ${{ env.CONFIG }} --no-build -o ${{ env.OUTPUT }} /p:version=${{ github.event.inputs.package_version }}

    - name: Create NuGet package file for Backoffice
      run: dotnet pack ./src/uSeoToolkit.Umbraco.Sitemap/uSeoToolkit.Umbraco.Sitemap.csproj -c ${{ env.CONFIG }} --no-build -o ${{ env.OUTPUT }} /p:version=${{ github.event.inputs.package_version }}

#    - name: Push packages to NuGet
#      run: dotnet nuget push "**/*.nupkg" -k ${{ secrets.NUGET_DEPLOY_KEY }} -s https://api.nuget.org/v3/index.json

    - name: upload-artifacts
      uses: actions/upload-artifact@v2
      with:
        name: Build-Results-${{ github.event.inputs.package_version }}
        path: ${{ env.OUTPUT }}/**/*

So let's go over it together and see what it all does! In the first few lines, we have the "name", "env" and "on". These are usually present in most Github Actions. The "name" is the name of the pipeline. With the "env", you can set some properties that you can use later in the pipeline and the "on" allows you to specify when this pipeline should run.

In SimpleRedirects, I had the pipeline run every time I make a new release. With uSeoToolkit, I can't quite do that because I'll also have package updates or bug fixes for just a single package. So in this case, I went with a manual dispatch, meaning that I can start a pipeline with a push of a button. Along with that, I can also specify the version of the NuGet package.

We then go to the jobs part.

jobs:
  build:

    runs-on: windows-latest

    steps:      
    - uses: actions/checkout@v2  

    - name: Setup .net core
      uses: actions/setup-dotnet@v1.4.0

This is quite easy. We want to run on a windows machine and use the latest code from our Github. Because we have an application on .Net Core, we also want to setup .Net Core.

- name: Restore dependencies
      run: dotnet restore ./src/uSeoToolkit.Umbraco.Sitemap/uSeoToolkit.Umbraco.Sitemap.csproj

    - name: Restore dependencies
      run: dotnet restore ./src/uSeoToolkit.Umbraco.Sitemap.Core/uSeoToolkit.Umbraco.Sitemap.Core.csproj

    - name: Build
      run: dotnet build ./src/uSeoToolkit.Umbraco.Sitemap.Core/uSeoToolkit.Umbraco.Sitemap.Core.csproj --configuration ${{ env.CONFIG }} --no-restore

    - name: Build
      run: dotnet build ./src/uSeoToolkit.Umbraco.Sitemap/uSeoToolkit.Umbraco.Sitemap.csproj --configuration ${{ env.CONFIG }} --no-restore

We then restore all dependencies for the project. We need to do this for the normal and the core project. Note that I don't restore it for the whole solution. This is because I would then be restoring packages that I don't need if I am only going to publish the sitemap package. After that, I am also building the project as I'll need the artifacts for the NuGet package.

    - name: Create NuGet package file for Core
      run: dotnet pack ./src/uSeoToolkit.Umbraco.Sitemap.Core/uSeoToolkit.Umbraco.Sitemap.Core.csproj -c ${{ env.CONFIG }} --no-build -o ${{ env.OUTPUT }} /p:version=${{ github.event.inputs.package_version }}

    - name: Create NuGet package file for Backoffice
      run: dotnet pack ./src/uSeoToolkit.Umbraco.Sitemap/uSeoToolkit.Umbraco.Sitemap.csproj -c ${{ env.CONFIG }} --no-build -o ${{ env.OUTPUT }} /p:version=${{ github.event.inputs.package_version }}

I'll then create a NuGet package for both the core and the backoffice package. I also tell the NuGet package that we don't have to do another build and that they can put the NuGet package on the output variable path. I also use the input that I've set at the start to specify the version of the NuGet package.

#    - name: Push packages to NuGet
#      run: dotnet nuget push "**/*.nupkg" -k ${{ secrets.NUGET_DEPLOY_KEY }} -s https://api.nuget.org/v3/index.json

Ideally, you would want to push your package to NuGet then. But because I am still testing the flow, I have commented it out for now.

    - name: upload-artifacts
      uses: actions/upload-artifact@v2
      with:
        name: Build-Results-${{ github.event.inputs.package_version }}
        path: ${{ env.OUTPUT }}/**/*

And the last step. I upload the artifacts of the output path. This is where the NuGet packages are located. It'll add the packages as a result of the pipeline so that you can download them when the pipeline is finished.

And that is all for the pipeline. Not that scary now, right? And that is also all for this week. There were a few code changes, but not big enough to write about. I hope you all liked the dive into the documentation and the pipelines and I'll hopefully see you again next week!