Publish Visual Studio for Mac extensions using Github Actions

Mar 19, 2023

In my previous article on Build Visual Studio for Mac Extensions using Github Actions, I went through how to build a Visual Studio for Mac extension using Github Actions. In this article, I would like to go into further detail of the same theme but now focusing on how to publish a Visual Studio for Mac extension to a private extension repository hosted in Github, using Github Actions

Create extensions repository

First thing we need to is to Create a new Github repository to publish our builds to. You can do this by either clicking on the New button from your Github Profile page under Repositories or by clicking Here

or by using the Github CLI

$ gh repo create my-vsmac-extension-repo --public

We need this to be a Public repository as we will need to access the raw contents of our repository and add it to Visual Studio for Mac

Now that we have an initial repo, we need to create a branch to commit to. You can’t push commits to an empty repo

echo "# delete-me" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:christianhelle/my-vsmac-extension-repo.git
git push -u origin main

Now that we have a repository, we need to Create a personal access token

and give it access to push commits to our new repository by giving the PAT the public_repo scope

Copy the PAT to the clipboard as we will use this PAT

Store the PAT as a Github Actions Secret in the repository that builds the Visual Studio for Mac extension. From the Settings page of that repo, unfold Secrets and variables, select Actions, then click on New Repository Secret.

Give the Secret a name, in this case ACTIONS_GITHUB_TOKEN and paste the PAT that we just created

Build and Publish .mpack file

The next thing we need to is to update our workflow to publish the .mpack file to the new repo we created. We do this by adding a new job to our existing workflow:

  deploy:

    runs-on: ubuntu-latest
    timeout-minutes: 10
    needs: build
    if: github.ref == 'refs/heads/main'

    steps:
    - uses: actions/checkout@v3
      with:
        repository: christianhelle/my-vsmac-extension-repo
        ref: 'main'
        token:  ${{ secrets.ACTIONS_GITHUB_TOKEN }}

    - uses: actions/download-artifact@v3
      with:
        path: artifacts

    - name: Remove version number from filename
      run: |
        mv artifacts/Extension/Sample-${{ env.VERSION }}.mpack Sample.mpack
        rm -rf artifacts
    
    - name: Git Commit Build Artifacts      
      run: |
        git config --global user.name "Continuous Integration"
        git config --global user.email "username@users.noreply.github.com"
        git add Sample.mpack
        git commit -m "Update .mpack file to version ${{ env.VERSION }}"
        git push

This new job will checkout our new Visual Studio for Mac extension repository, which in this example I called my-vsmac-extension-repo. We set the token parameter because we will be committing back to this repository. Then it downloads the build artifacts from the previous build job to a folder called artifacts. You can only provide one version of your extension at a time in a Visual Studio for Mac extension repository so we need to strip the version number out of the filename. Lastly, add and commit the .mpack file to the extensions repository

Here’s the full contents of our workflow:

name: Build

on:
  workflow_dispatch:
  push:

env:
  VERSION: 1.0.${{ github.run_number }}

jobs:

  build:

    runs-on: macos-latest
    timeout-minutes: 10

    steps:
    - uses: actions/checkout@v3

    - name: Update Extension Version Info
      run: |
        sed -i -e 's/1.0/${{ env.VERSION }}/g' ./AddinInfo.cs
        cat ./AddinInfo.cs
      working-directory: src

    - name: Restore
      run: dotnet restore
      working-directory: src

    - name: Build
      run: /Applications/Visual\ Studio.app/Contents/MacOS/vstool build --configuration:Release $PWD/Sample.csproj
      working-directory: src

    - name: Pack
      run: /Applications/Visual\ Studio.app/Contents/MacOS/vstool setup pack $PWD/src/bin/Release/net7.0/Sample.dll -d:$PWD

    - name: Archive binaries
      run: zip -r Binaries.zip src/bin/Release/net7.0/

    - name: Publish binaries
      uses: actions/upload-artifact@v2
      with:
        name: Binaries
        path: Binaries.zip

    - name: Rename build output
      run: mv *.mpack Sample-${{ env.VERSION }}.mpack

    - name: Publish artifacts
      uses: actions/upload-artifact@v2
      with:
        name: Extension
        path: Sample-${{ env.VERSION }}.mpack

  deploy:

    runs-on: ubuntu-latest
    timeout-minutes: 10
    needs: build
    if: github.ref == 'refs/heads/main'

    steps:
    - uses: actions/checkout@v3
      with:
        repository: christianhelle/my-vsmac-extension-repo
        ref: 'main'
        token:  ${{ secrets.ACTIONS_GITHUB_TOKEN }}

    - uses: actions/download-artifact@v3
      with:
        path: artifacts

    - name: Remove version number from filename
      run: |
        mv artifacts/Extension/Sample-${{ env.VERSION }}.mpack Sample.mpack
        rm -rf artifacts
    
    - name: Git Commit Build Artifacts      
      run: |
        git config --global user.name "Continuous Integration"
        git config --global user.email "username@users.noreply.github.com"
        git add Sample.mpack
        git commit -m "Update .mpack file to version ${{ env.VERSION }}"
        git push

A successful run of this build should look like something like this:

Take a look at the extensions repo to make sure that the .mpack file got pushed correctly

Build the .mrep files

Now that we have .mpack files getting pushed into the extensions repository, we can setup a Github workflow that creates the Visual Studio for Mac .mrep files upon every push. The .mrep file is an XML file that contains meta data about the .mpack files in the extensions repository

Before we can grant Github Actions Read and Write permissions to its own repository. To do this, in the extensions repository Settings, unfold Actions and select General, enable Read and Write permissions under Workflow Permissions

Now we create a workflow:

name: Build

on:
  workflow_dispatch:
  push:
    paths-ignore:
      - '**/*'
      - '!**/*.mpack'
      - '!.github/workflows/build.yml'

jobs:
  build:

    runs-on: macos-latest
    timeout-minutes: 10

    env: 
      CI_COMMIT_MESSAGE: Continuous Integration Build Artifacts
      CI_COMMIT_AUTHOR: Continuous Integration

    steps:
    - uses: actions/checkout@v3

    - name: stable - vstool setup rep-build
      run: /Applications/Visual\ Studio.app/Contents/MacOS/vstool setup rep-build $PWD

    - name: Publish Stable Repo
      uses: actions/upload-artifact@v2
      with:
        name: Stable
        path: |
          *.mrep
          index.html
    
    - name: Git Commit Build Artifacts
      run: |
        git config --global user.name "${{ env.CI_COMMIT_AUTHOR }}"
        git config --global user.email "username@users.noreply.github.com"
        git add .
        git commit -m "${{ env.CI_COMMIT_MESSAGE }}"
        git push

We can either manually run the workflow above, or we can just trigger it by running the build workflow on the Visual Studio for Mac extension sample.

Once the workflow above has ran, the extensions repository should look something like this:

Thw workflow above ran vstool setup rep-build $PWD and committed the output files to its own repo. The command vstool setup rep-build $PWD produces 3 files, index.html, main.mrep, and root.mrep

The root.mrep file describes the files in th repository and looks something like this:

<?xml version="1.0" encoding="utf-8"?>
<Repository xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Addin>
    <Url>Sample.mpack</Url>
    <Addin>
      <Id>Sample</Id>
      <Namespace>Sample</Namespace>
      <Name>My First Extension</Name>
      <Version>0.1.17</Version>
      <BaseVersion />
      <Author>Christian Resma Helle</Author>
      <Copyright />
      <Url />
      <Description>My first Visual Studio for Mac extension</Description>
      <Category>IDE extensions</Category>
      <Dependencies />
      <OptionalDependencies />
      <Properties>
        <Property name="DownloadSize">3188</Property>
      </Properties>
    </Addin>
  </Addin>
</Repository>

The main.mrep files points to the root.mrep file. You will be adding the direct link to the main.mrep file from Visual Studio for Mac

<?xml version="1.0" encoding="utf-8"?>
<Repository xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Repository>
    <Url>root.mrep</Url>
    <LastModified>2023-03-20T15:31:42.3222075+00:00</LastModified>
  </Repository>
</Repository>

And lastly, index.html is a naive attempt to create a HTML page describing the available extensions

<html><body>
<h1>Add-in Repository</h1>
<p>This is a list of add-ins available in this repository.</p>
<table border=1><thead><tr><th>Add-in</th><th>Version</th><th>Description</th></tr></thead>
<tr><td>My First Extension</td><td>0.1.17</td><td>My first Visual Studio for Mac extension</td></tr>
</table>
</body></html>

Add extension repository to Visual Studio

Now all we need is to add a new custom extension repository to Visual Studio for Mac so we can download the extensions all from the IDE, and also see when there are updates coming in. To do this, we need to get the URL to the Raw main.mrep file. We do this by opening main.mrep from Github and getting the URL from the Raw link

This should be something like https://raw.githubusercontent.com/christianhelle/my-vsmac-extension-repo/main/main.mrep. We need to add this as an Extension Source to Visual Studio for Mac. This is done from Preferences, then scroll down on the side menu to Extensions, select Sources, then click on Add, then paste the Raw link to main.mrep

After this we should be able to see our extension from the Visual Studio for Mac Extensions screen

I hope you found this useful and get inspired to start building extensions of your own. If you’re interested in the full source code then you can checkout the Example VSMac extension project and the Visual Studio for Mac extension repository

Share this on:

Build Visual Studio for Mac Extensions using Github Actions

Mar 16, 2023

In my previous article on Extending Visual Studio for Mac 2022, I went through a step-by-step walkthrough to build a simple Visual Studio for Mac extension that does adds a menu item under the Edit menu, which when clicked, will write // Hello at the current cursor position of the currently active document.

Visual Studio for Mac extensions can be created using SDK Style .NET projects use .NET 7.0 as the target framework. The first requirement for setting up a build pipeline is being able to build the project from the command line. Using the example from the the previous article, let’s build the Sample project using a Github Actions workflow

In case you are new to Github Actions, you should create the folder /.github/workflows in your git repo, then create a workflow file under the folder we just created.

For this example, let’s create a file called build.yml.

Here’s the contents of our workflow:

name: Build

on:
  workflow_dispatch:
  push:

env:
  VERSION: 1.0.${{ github.run_number }}

jobs:

  build:

    runs-on: macos-latest
    timeout-minutes: 10

    steps:
    - uses: actions/checkout@v3

    - name: Update Extension Version Info
      run: |
        sed -i -e 's/1.0/${{ env.VERSION }}/g' ./AddinInfo.cs
        cat ./AddinInfo.cs
      working-directory: src

    - name: Restore
      run: dotnet restore
      working-directory: src

    - name: Build
      run: /Applications/Visual\ Studio.app/Contents/MacOS/vstool build --configuration:Release $PWD/Sample.csproj
      working-directory: src

    - name: Pack
      run: /Applications/Visual\ Studio.app/Contents/MacOS/vstool setup pack $PWD/src/bin/Release/net7.0/Sample.dll -d:$PWD

    - name: Archive binaries
      run: zip -r Binaries.zip src/bin/Release/net7.0/

    - name: Publish binaries
      uses: actions/upload-artifact@v2
      with:
        name: Binaries
        path: Binaries.zip

    - name: Rename build output
      run: mv *.mpack Sample-${{ env.VERSION }}.mpack

    - name: Publish artifacts
      uses: actions/upload-artifact@v2
      with:
        name: Extension
        path: Sample-${{ env.VERSION }}.mpack

Let’s break the workflow job steps down into detail…

Step 1) Checkout the branch.

Pretty a much a standard first for most Github Action workflows

Step 2) Update the version info of the extension.

For this naive example let’s just call it version 1.0.xxx where xxx is the workflow run number. We get the Github Action workflow run number from ${{ github.run_number }}. Let’s store this in an environment variable called VERSION. We then want to update the version number in the AddinInfo.cs file

To do this, we use the the sed (stream editor) command to replace all instances of 1.0 with 1.0.xxx.

We do this by running:

$ sed -i -e 's/1.0/$/g' ./AddinInfo.cs

The contents of AddinInfo.cs may look something like this:

using Mono.Addins;
using Mono.Addins.Description;

[assembly: Addin(Id = "Sample", Namespace = "Sample", Version = "1.0")]
[assembly: AddinName("My First Extension")]
[assembly: AddinCategory("IDE extensions")]
[assembly: AddinDescription("My first Visual Studio for Mac extension")]
[assembly: AddinAuthor("Christian Resma Helle")]

Step 3) Restore package reference

This simple step is where the workflow should basically just run dotnet restore from the folder that contains the solution file

Step 4) Build the extension

We want to build the project in Release configuration using the CLI. Normally we can do this using dotnet build -c Release which works fine if you have previously built a Visual Studio for mac extension on the machine you’re working on but if you are building it in a new machine that has previously never build a Visual Studio for Mac extension then you most likely will need to run the Visual Studio Tool Runner a.k.a. vstool but because we are probably running from a short lived virtual machine, we can’t assume that running dotnet build -c Release will work on the first try.

Instead of running dotnet build we should instead do something like run the Visual Studio Tool Runner build command

$ /Applications/Visual\ Studio.app/Contents/MacOS/vstool build --configuration:Release $PWD/Sample.csproj

You need to specify the absolute path to the project file, but you can simplify this by getting the present working directory from the PWD command

Step 5) Package the extension

Now that the extension is built, we now need to package it to be able to distribute it. To create a MonoDevelop package file .mpack you need to run the Visual Studio Extension Setup Utility pack command

$ /Applications/Visual\ Studio.app/Contents/MacOS/vstool setup pack [absolute path to main output DLL] -d:[absolute path to output folder]

A little tip for getting the absolute path is to use $PWD. So if you created your project under the ~/projects/my-extension folder and this is currently your working directory then you can do something like:

$ /Applications/Visual\ Studio.app/Contents/MacOS/vstool setup pack $PWD/Sample.dll -d:$PWD

Sample.dll is the build output of the project we just built

The command above will produce the output ~/projects/my-extension/Sample.mpack

Step 5) Package the binaries

Archive the binary files so we can use them as build artifiacts

$ zip -r Binaries.zip src/bin/Release/net7.0/

Step 6) Publish binaries as build artifacts

In this step we will publish the newly created Binaries.zip as a build artifact

Step 7) Rename built output

We do this so to help users who might have download multiple verssions of the extension be able to keep older versions of the extension. This is completely optional, but is something I find to be a good practice

Uploading artifacts uses the actions/upload-artifact@v2 task

Step 8) Publish .mpack file as build artifacts

This is pretty straight forward. You start off by using the actions/upload-artifact@v2 task. This workflow allows the developer to the filename of the artifact, and also which folder to publish as build artifacts

Build Output

If everything succeeds then we should be able to see the results of the build in Github Actions. At the bottom of the content section for every build should have 2 artifacts, the binary files and the .mpack file itself.

There are 2 artifacts in the build called Binaries and Extensions. They are packed as zip files when downloaded

I hope you found this useful and get inspired to start building extensions of your own. If you’re interested in the full source code then you can grab it here

Share this on:

Extending Visual Studio for Mac 2022

Mar 9, 2023

This is step by step walkthrough guide to getting started with developing extensions for Visual Studio for Mac 2022 with explanations, code examples, and a couple of links to offical documentation

The extensibility story for Visual Studio for Mac was almost non-existent for a while, and the documentation for getting started was really outdated. Visual Studio for Mac was originally a re-branding of Xamarin Studio, which was built over MonoDevelop and the extensibility SDK’s we used for the longest time was all from the old MonoDevelop Addin libraries. The original getting started guide from MonoDevelop is still somewhat correct, but the libraries referred to in the guide will no longer build.

For Visual Studio for Mac 2022 this has changed and now we can create Visual Studio for Mac extensions using the Microsoft.VisualStudioMac.Sdk library that we can install from nuget.org. To make things even better, we can now break free of our old .NET Framework 4.x shackles and start targetting .NET 7.0. and all it’s goodness

As of the time I’m writing this, there is still no File -> New -> Extension Project experience, but it’s not hard to get started either.

Walkthrough

In this walkthrough, we will build a simple Visual Studio for Mac extension that adds the Insert Text menu item to the Edit menu. All this can do is to insert the text // Hello to the active document from the current cursor position

Step 1 - Create New Project

Let’s start with creating a new project called Sample.csproj

Here’s how a csproj file for an empty Visual Studio for Mac extension project looks like:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.VisualStudioMac.Sdk" Version="17.0.0" />
  </ItemGroup>
</Project>

Step 2 - Addin info

A Visual Studio for Mac extension has metadata about its name, version, dependencies, etc. It also defines any number of extensions that plug into extension points defined by other extensions, and can also define extension points that other extensions can extend.

Let’s define some AddIn information in a file called AddinInfo.cs

using Mono.Addins;
using Mono.Addins.Description;

[assembly: Addin(Id = "Sample", Namespace = "Sample", Version = "1.0")]
[assembly: AddinName("My First Extension")]
[assembly: AddinCategory("IDE extensions")]
[assembly: AddinDescription("My first Visual Studio for Mac extension")]
[assembly: AddinAuthor("Christian Resma Helle")]

The combined Id and Namespace from Addin should be unique among all Visual Studio for Mac extensions. The other attributes are self-explanatory

Step 3 - Addin Manifest

Now that the Addin is defined, we can add some extensions.

We do this by defining the Manifest.addin.xml file

<?xml version="1.0" encoding="UTF-8"?>
<ExtensionModel>
    <Extension path = "/MonoDevelop/Ide/Commands/Edit">
        <Command id = "Sample.SampleCommands.InsertText"
            _label = "Insert Text"
            defaultHandler = "Sample.InsertTextHandler" />
    </Extension>

    <Extension path = "/MonoDevelop/Ide/MainMenu/Edit">
        <CommandItem id="Sample.SampleCommands.InsertText" />
    </Extension>
</ExtensionModel>

This extension defines a command for the command system. The Command ID should correspond to an enum value. The _label attribute is the display name of the command. The defaultHandler attribute is the full type name of the CommandHandler implementation that will execute when the extension executes

The Command System provides ways to control the availability, visibility and handling of commands depending on context.

Commands can be bound to keyboard shortcuts and can be inserted into menus. In this exaple, we are going to insert the InsertText command into the main Edit menu with another extension.

Step 4 - Implement the CommandHandler

Now that the InsertText command is registered, we need to implement a command handler. The simplest way to use it is with a default handler, which is a class that implements MonoDevelop.Components.Commands.CommandHandler. Let’s implement CommandHandler as InsertTextHandler to be only available when an active document is open

We will also need to create the SampleCommands enum

using MonoDevelop.Components.Commands;
using MonoDevelop.Ide;
using MonoDevelop.Ide.Gui;
using System;

namespace Sample
{
    public class InsertTextHandler : CommandHandler
    {
        protected override void Run()
        {
            var textBuffer = IdeApp.Workbench.ActiveDocument.GetContent<ITextBuffer>();
            var textView = IdeApp.Workbench.ActiveDocument.GetContent<ITextView>();
            textBuffer.Insert(textView.Caret.Position.BufferPosition.Position, "// Hello");
        }

        protected override void Update(CommandInfo info)
        {
            var textBuffer = IdeApp.Workbench.ActiveDocument.GetContent<ITextBuffer>();
            if (textBuffer != null && textBuffer.AsTextContainer() is SourceTextContainer container)
            {
                var document = container.GetTextBuffer();
                if (document != null)
                {
                    info.Enabled = true;
                }
           }
        }
    }

    public enum SampleCommands
    {
        InsertText,
    }
}

Step 5 - Package the extension

This can be done by right clicking on the extension project from Visual Studio for Mac then selecting Pack from the context menu

You can also do it from the command line. With the new SDK, Microsoft.VisualStudioMac.Sdk, you can build the project from the command line simply by using dotnet build. Running dotnet build will ONLY build the project, it will not create the distributable .mpack package.

Let’s start with building the project in Release configuration

$ dotnet build -c Release Sample.csproj

This will produce the bin/Release/net7.0/Sample.dll file

To create the .mpack package from the command line, we need to use the Visual Studio Tool Runner a.k.a. vstool. The Visual Studio Tool Runner is included in the Visual Studio for Mac installation. The Visual Studio Tool Runner is available from the following path

$ /Applications/Visual\ Studio.app/Contents/MacOS/vstool

We need to run the Visual Studio Extension Setup Utility pack command

$ /Applications/Visual\ Studio.app/Contents/MacOS/vstool setup pack [absolute path to main output DLL] -d:[absolute path to output folder]

$ /Applications/Visual\ Studio.app/Contents/MacOS/vstool setup pack $PWD/Sample.dll -d:$PWD

The command above will produce the output ~/projects/my-extension/Sample.mpack

Step 6 - Test the extension

Debugging a Visual Studio for Mac is possible, but doesn’t come out of the box. To enable Debugging the extension from Visual Studio for Mac we need to add the following to our C# project

<PropertyGroup Condition=" '$(RunConfiguration)' == 'Default' ">
  <StartAction>Program</StartAction>
  <StartProgram>\Applications\Visual Studio.app\Contents\MacOS\VisualStudio</StartProgram>
  <StartArguments>--no-redirect</StartArguments>
  <ExternalConsole>true</ExternalConsole>
</PropertyGroup>

Now our Sample project should look something like this:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(RunConfiguration)' == 'Default' ">
    <StartAction>Program</StartAction>
    <StartProgram>\Applications\Visual Studio.app\Contents\MacOS\VisualStudio</StartProgram>
    <StartArguments>--no-redirect</StartArguments>
    <ExternalConsole>true</ExternalConsole>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.VisualStudioMac.Sdk" Version="17.0.0" />
  </ItemGroup>
</Project>

Debugging the extension will basically start another instance of Visual Studio for Mac where you can test your extension

Try it out and if all goes well the Edit menu should have the Insert Text item at the bottom

Step 7 - Install extension

If you followed Step 5, then you should already have a .mpack at hand. To install a Visual Studio for Mac extension, you need to follow these steps:

You need to restart Visual Studio for Mac at this point before you can see our new extension under the Edit menu

I hope you found this useful and get inspired to start building extensions of your own. If you’re interested in the full source code then you can grab it here

Share this on:

Page: 1 of 35 Next