Skip to main content
Version: 2.0.0-preview

Creating a C# Project for Extensions

This article explains how to create an empty C# project for Beutl extensions.

This guide introduces the methods using Visual Studio Code or Visual Studio. Beutl 2.0 ships an MSBuild SDK called Beutl.Extensibility.Sdk that wires up the target framework, language defaults, the standard package references (Beutl.Api, Beutl.Extensibility, Beutl.ProjectSystem, Beutl.NodeGraph, Beutl.Editor, Beutl.Controls, Beutl.Engine.SourceGenerators), and the sideload output path. Using it keeps the csproj small.

tip

Pick the SDK version that matches the Beutl release you target. The SDK and the Beutl runtime packages are versioned together (for example, 2.0.0-preview.9). You can override the resolved package versions with the BeutlPackagesVersion property if you need a different combination.

Visual Studio Code​

  1. Use the terminal to create a class library.
dotnet new classlib -o MyBeutlExtension

Ensure the directory structure is as follows:

MyBeutlExtension
┣━ obj
┃  ┗━ (...)
┣━ Class1.cs
┗━ MyBeutlExtension.csproj
  1. Run the following commands to generate nuget.config and add the package source. The Beutl SDK and runtime packages are distributed via the nuget.beditor.net feed.
dotnet new nugetconfig
dotnet nuget add source "https://nuget.beditor.net/v3/index.json" --name nuget.beditor.net
  1. Edit the generated MyBeutlExtension.csproj as follows:
<Project Sdk="Beutl.Extensibility.Sdk/2.0.0-preview.9">
  <PropertyGroup>
    <PackageId>MyBeutlExtension</PackageId>
    <Title>Sample Extension</Title>
    <Description>Sample</Description>
    <PackageTags>sample</PackageTags>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <RepositoryUrl>url/to/repository</RepositoryUrl>

    <!-- Copy Debug builds to the sideload directory. -->
    <DebugApplication Condition="'$(Configuration)'=='Debug'">true</DebugApplication>
  </PropertyGroup>
</Project>

The SDK takes care of:

  • Setting TargetFramework to net10.0, plus ImplicitUsings and Nullable to enable.
  • Adding PackageReferences to Beutl.Api, Beutl.Extensibility, Beutl.ProjectSystem, Beutl.NodeGraph, Beutl.Editor, Beutl.Controls, and the Beutl.Engine.SourceGenerators analyzer.
  • Redirecting the output path to ~/.beutl/sideloads/<AssemblyName> when DebugApplication is true.
info

The preview.9 SDK references Beutl.Engine.SourceGenerators as a build-only analyzer with PrivateAssets="all". The manual workaround needed by preview.8 and earlier to keep the generator out of package dependencies is no longer necessary.

This completes the creation of an empty C# project for extensions.

Customizing references​

Set any of these properties to false if you want to opt out of a specific auto-reference:

  • BeutlAutoReferenceAll
  • BeutlAutoReferenceApi
  • BeutlAutoReferenceExtensibility
  • BeutlAutoReferenceProjectSystem
  • BeutlAutoReferenceNodeGraph
  • BeutlAutoReferenceEditor
  • BeutlAutoReferenceControls
  • BeutlAutoReferenceSourceGenerators

Override BeutlSideloadPath to choose the sideload directory. Otherwise, the SDK uses sideloads/<AssemblyName> under BEUTL_HOME, or under ~/.beutl when that environment variable is unset.

Visual Studio​

  1. Open Visual Studio and click File > New > Project. Create Visual Studio Project

  2. Select Class Library and click Next. Select Class Library

  3. Enter the project name and location, then click Next. Confirm Name and Location

  4. Select .NET 10.0 as the framework. (The Beutl.Extensibility.Sdk will override this anyway, but pick a framework that matches the Beutl release you target so IntelliSense is correct from the start.)

  5. Click Create.

Ensure the directory structure is as follows:

MyBeutlExtension
┣━ MyBeutlExtension
┃  ┣━ obj
┃  ┃  ┗━ (...)
┃  ┣━ Class1.cs
┃  ┗━ MyBeutlExtension.csproj
┗━ MyBeutlExtension.sln
  1. Run the following commands to generate nuget.config and add the package source.
dotnet new nugetconfig
dotnet nuget add source "https://nuget.beditor.net/v3/index.json" --name nuget.beditor.net
  1. Edit the generated MyBeutlExtension.csproj as follows:
<Project Sdk="Beutl.Extensibility.Sdk/2.0.0-preview.9">
  <PropertyGroup>
    <PackageId>MyBeutlExtension</PackageId>
    <Title>Sample Extension</Title>
    <Description>Sample</Description>
    <PackageTags>sample</PackageTags>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <RepositoryUrl>url/to/repository</RepositoryUrl>

    <DebugApplication Condition="'$(Configuration)'=='Debug'">true</DebugApplication>
  </PropertyGroup>
</Project>
  1. Click Restore NuGet Packages to ensure that NuGet dependencies are restored correctly. Restore NuGet Packages

This completes the creation of an empty C# project for extensions.

Source​