DEV Community: Sebastiaan Janssen

Setting Up a New Umbraco Package Dev Environment with Umbraco.AI

Sebastiaan Janssen — Thu, 19 Mar 2026 09:30:57 +0000

This guide walks through setting up a new Umbraco package project called Umbraco.Community.AI.Woowoo that extends Umbraco.AI. Rather than starting from scratch with a blank solution, the goal is a proper package structure from day one: the right project layout, a frontend build pipeline, uSync, GitHub Actions for NuGet publishing, the works.

That's where Lotte's Opinionated Package Starter Template comes in. Lotte has done the hard work of figuring out what a well-structured Umbraco package solution should look like, and turned it into a dotnet new template. Pair that with Matt Brailsford's Umbraco.AI Kitchen Sink install guide, and you have everything you need to go from zero to a fully wired-up Umbraco.AI development environment.

This post walks through the full setup, including the Linux-specific gotcha to watch out for.

Prerequisites

Before starting, make sure you have:

.NET 10 SDK -- Umbraco 17 targets .NET 10
Node.js and npm -- the package project uses Vite and TypeScript for its frontend
A GitHub account -- the template wires up a GitHub remote and includes GitHub Actions for NuGet publishing

Step 1: Install the template

Install the package starter template from NuGet:

dotnet new install Umbraco.Community.Templates.PackageStarter

You should see output ending with something like:

Success: Umbraco.Community.Templates.PackageStarter::X.X.X installed the following templates:
  umbracopackagestarter

What does this template give you?

When you scaffold from it, you get a complete two-project solution:

src/AI.Woowoo/ -- the package project, with Vite + TypeScript frontend (via the umbraco-extension template) and a NuGet-configured .csproj
src/AI.Woowoo.TestSite/ -- an Umbraco 17 test site with uSync pre-configured
src/AI.Woowoo.sln -- the solution file, with the TestSite already referencing the package project
.github/workflows/release.yml -- a GitHub Action that publishes to NuGet when you push a version tag
umbraco-marketplace.json, README stubs, issue templates, and an MIT LICENSE

That's a solid foundation for package development, covering all the scaffolding that would otherwise take hours to set up from scratch.

Step 2: Scaffold the solution

dotnet new umbracopackagestarter -n AI.Woowoo -an "Your Name" -gu YourGitHubUsername -gr Umbraco.Community.AI.Woowoo --allow-scripts yes

What each parameter does:

Parameter	What it does
`-n AI.Woowoo`	The base name for the solution. The template prepends `Umbraco.Community.`, so the NuGet package ID becomes `Umbraco.Community.AI.Woowoo`
`-an "Your Name"`	Author name, used in the `.csproj` and marketplace metadata
`-gu YourGitHubUsername`	Your GitHub username, used to construct the repo URL
`-gr Umbraco.Community.AI.Woowoo`	The GitHub repository name
`--allow-scripts yes`	Bypasses the security prompt for the post-creation script (`setup.cmd`), which runs `npm install` as part of the `umbraco-extension` template setup

This will take a few minutes -- npm install runs as part of the setup. Wait for the "All done!" message.

Step 3: The Linux/macOS gotcha -- `setup.cmd` won't run

If you're on Windows, you can skip this section. The template's setup.cmd script will have run fine and your solution is ready. Jump straight to Step 4.

On Linux and macOS, the setup.cmd post-creation script fails with "Permission denied" because it's a Windows batch file. The template files are all created correctly -- the script just doesn't run, so the git repository, the frontend scaffolding, the solution wiring, and a few other things need to be done manually.

Here's everything the script would have done, translated into commands you can run:

# Initialise the git repository
cd AI.Woowoo
git init
git branch -M main
git remote add origin https://github.com/YourGitHubUsername/Umbraco.Community.AI.Woowoo.git

# Make sure you have the latest Umbraco dotnet templates
dotnet new install Umbraco.Templates --force

# Scaffold the package project inside src/
cd src
dotnet new umbraco-extension -n "AI.Woowoo" --site-domain "https://localhost:44361" --include-example

# The template creates two .csproj files -- swap them so the NuGet-configured one is active
cd AI.Woowoo
rm AI.Woowoo.csproj
mv AI.Woowoo_nuget.csproj AI.Woowoo.csproj

# Wire everything up in the solution
cd ..
dotnet sln add "AI.Woowoo"
dotnet add "AI.Woowoo.TestSite/AI.Woowoo.TestSite.csproj" reference "AI.Woowoo/AI.Woowoo.csproj"

Tip: The repo root also contains a setup.mjs file -- a Node.js replacement for setup.cmd that works cross-platform. If it's present, running node setup.mjs handles all the steps above.

Step 4: Build the frontend & verify the base site

Before layering anything on top, confirm the scaffolded solution actually works. Build the frontend assets first:

cd src/AI.Woowoo/Client
npm install
npm run build

You should see Vite output with files written to dist/. Now start the TestSite:

cd ../../AI.Woowoo.TestSite
dotnet run

The launchSettings.json included by the template automatically sets ASPNETCORE_ENVIRONMENT=Development, so you don't need to set it yourself. On first run, Umbraco installs itself unattended -- watch the terminal output for the URL (typically https://localhost:44331 or similar).

Email: admin@example.com
Password: 1234567890

Check two things:

Navigate to the Content section -- an "Example Dashboard" should be there (this is the example added by the --include-example flag in the umbraco-extension template)
Navigate to /umbraco/swagger -- the Umbraco Management API document should appear in the dropdown

Once everything looks good, hit Ctrl+C to stop the site. You now have a clean, working base to build on.

Step 5: Add the Umbraco.AI packages

All the Umbraco.AI packages go into the TestSite project, not the package project. The package project stays clean -- it will only reference Umbraco.AI (or specific Umbraco.AI interfaces) when actually needed for package code. The TestSite is the development host.

Run these from the repo root (AI.Woowoo/):

# The Clean starter kit adds a demo content structure to the site
dotnet add "src/AI.Woowoo.TestSite" package Clean

# The core Umbraco.AI integration layer
dotnet add "src/AI.Woowoo.TestSite" package Umbraco.AI

# Addons
dotnet add "src/AI.Woowoo.TestSite" package Umbraco.AI.Prompt
dotnet add "src/AI.Woowoo.TestSite" package Umbraco.AI.Agent
dotnet add "src/AI.Woowoo.TestSite" package Umbraco.AI.Agent.Copilot --prerelease

# AI providers
dotnet add "src/AI.Woowoo.TestSite" package Umbraco.AI.Amazon
dotnet add "src/AI.Woowoo.TestSite" package Umbraco.AI.Anthropic
dotnet add "src/AI.Woowoo.TestSite" package Umbraco.AI.Google
dotnet add "src/AI.Woowoo.TestSite" package Umbraco.AI.MicrosoftFoundry
dotnet add "src/AI.Woowoo.TestSite" package Umbraco.AI.OpenAI

A couple of notes:

Umbraco.AI.Agent.Copilot requires --prerelease because it's still in alpha. The other packages are stable.
All five provider packages (Amazon Bedrock, Anthropic, Google, Microsoft Foundry, OpenAI) are installed so the environment is ready for any AI provider you or contributors want to test against. The seed data in the next step only activates the OpenAI connection, but the others are configured and waiting.

Check Matt's install guide if you're following along later -- version numbers may have moved on. The Umbraco.AI documentation covers all the extensibility points in detail if you want to go further.

Step 6: Add the seed demo data

Matt has a helpful GitHub Gist that seeds a full Umbraco.AI demo configuration: a connection, profile, context, prompts, and agents. It's a self-registering C# file -- drop it in the project and it registers itself via Umbraco's component system and seeds the data on first startup. It's also idempotent, so safe to leave in place.

curl -o src/AI.Woowoo.TestSite/UmbracoAISeedData.cs \
  "https://gist.githubusercontent.com/mattbrailsford/199d0b45e926ffb122fa96467039bd90/raw/UmbracoAISeedData.cs?v=2"

API key (optional)

The seed data installs an OpenAI connection with a dummy key. The site runs fine without a real key -- all the AI configuration gets seeded into the backoffice, the connection just won't be functional. Replace the key later through the Umbraco.AI section in the backoffice once everything is up and running.

Don't have an OpenAI key? Google hands out free Gemini API keys via Google AI Studio -- no credit card required. Hit "Create API key" in the top right, or "Get API key" in the left sidebar. The free tier is generous enough for development. If you go this route, use the Umbraco.AI.Google provider and configure the connection in the backoffice accordingly.

Step 7: Run and verify

cd src/AI.Woowoo.TestSite
dotnet run

Once it's running, log in (admin@example.com / 1234567890) and navigate to the Umbraco.AI section in the backoffice. You should see:

A seeded OpenAI connection
A profile
A context
Several prompts
Several agents

If you added a real API key, try running a prompt or agent to confirm the connection is live.

Step 8: Make the initial commit

Before staging everything, do a quick sanity check: open UmbracoAISeedData.cs and confirm there's no real API key in there.

git add .
git commit -m "chore: initial scaffold from Lotte's Opinionated Package Starter Template"
git push -u origin main

Prerequisite: before pushing, go to GitHub and create a new empty repository named Umbraco.Community.AI.Woowoo (skip the readme, license, and gitignore options -- the template already created those locally). The template already configured the remote, so git push goes straight to the right place.

What's next

The environment is now ready:

src/AI.Woowoo/ -- the package project, clean and ready for package code
src/AI.Woowoo.TestSite/ -- a full Umbraco 17 + Umbraco.AI host to develop and test against, with demo data seeded
GitHub Actions configured for NuGet publishing on version tags
All five AI providers installed and ready to configure

When it comes to implementing the package itself, the first thing to add to src/AI.Woowoo/AI.Woowoo.csproj is a reference to Umbraco.AI.Core -- the package that contains all the extension points (custom tools, middleware, guardrail evaluators, etc.):

dotnet add src/AI.Woowoo package Umbraco.AI.Core --version 1.6.0

Note that Umbraco.AI.Core 1.6.0 requires Umbraco.Cms 17.1.0 or higher. The template scaffolds the package project against 17.0.0, so bump the four Umbraco.Cms references in the same file to 17.1.0 when you add this.

The next step is implementing the Umbraco.Community.AI.Woowoo package itself -- but that's a story for another post.

Using JWT tokens to access an UmbracoApiController

Sebastiaan Janssen — Mon, 24 Jul 2023 10:46:53 +0000

So far, JWT has been eluding me, I haven't had the time to look into them, I just knew they existed and worked by sending a header.

Today, I was following a question from Navorski about using JWT authentication on an UmbracoApiController, I enjoyed the responses from Dennis who had clearly done this before.

It seemed like this was easy enough to follow, so I decided to try it out for myself and see how far I could get. As it turns out, I was fearing them more than I should have done! Let's have a look.

First we need to tell our Web App (Umbraco) that JWT is one of the way to authenticate. For that, we need to install a NuGet package first to help us out with that:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

The next thing to do is to set up some configuration items, which can be added after the "Umbraco": section.

  "Jwt": {
    "Key": "ihuEAzo7BxW09LTTNKCz",
    "Issuer": "https://localhost:44336/",
    "Audience": "https://localhost:44336/"
  }

In the appSettings.json it looks like this:

The Key I generated here is a secret, please don't copy it but create a unique key for yourself.

Once that is installed, the linked tutorial tells us to add some things to Startup.cs. Personally, I like adding things using an IComposer to make my code more portable in case I want to reuse it or put it in a package, for example.

So I end up with the following code, that does the same thing as it would have done if I had added it to Startup.cs.

using System.Text;
using Microsoft.IdentityModel.Tokens;
using Umbraco.Cms.Core.Composing;

namespace JwtTest;

public class JwtComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.AddAuthentication().AddJwtBearer(options =>
        {
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidateAudience = true,
                ValidateLifetime = true,
                ValidateIssuerSigningKey = true,
                ValidIssuer = builder.Config["Jwt:Issuer"],
                ValidAudience = builder.Config["Jwt:Audience"],
                IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(builder.Config["Jwt:Key"]))
            };
        });
    }
}

Whenever we request JWT token authentication, this code will run.

Next up, we can make an UmbracoApiController with an example endpoint:

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Web.Common.Controllers;

namespace JwtTest;

public class TestApiController : UmbracoApiController
{
    public ActionResult<string> GetAuthenticatedMessage()
    {
        return "You need to be authenticated to see this message.";
    }
}

Now, when we run the site and go to https://localhost:44336/umbraco/api/TestApi/GetAuthenticatedMessage, we see the message You need to be authenticated to see this message.. Great! But the message is a lie, we didn't request or provide any authentication. Let's add some.

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Web.Common.Controllers;

namespace v12final;

public class TestApiController : UmbracoApiController
{
    [Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme)]
    public ActionResult<string> GetAuthenticatedMessage()
    {
        return "You need to be authenticated to see this message.";
    }
}

The Authorize attribute now requires us to provide a JWT bearer token in order for the request to succeed. When we now try to access the same endpoint, we get a nice 401 Unauthorized error.

We're getting there! We need a way to obtain a JWT authorization token now. Normally you'd do that by verifying a user is authenticated in the system, I'll leave that part as a exercise to the reader and focus on generating the token we need. So in the next snippet of code, we allow anyone who provides us with any username and password to get a token.

⚠️ Don't do this in real life, make sure you only hand out tokens to trusted parties, verify you can trust them.

The following code was added to the same TestApiController we had above:

private readonly IConfiguration _config;

public TestApiController(IConfiguration config)
{
    _config = config;
}

[HttpPost]
public ActionResult<string> GenerateJwtToken([FromBody] UserModel user)
{
    // TODO: Do something to verify username/password

    var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_config["Jwt:Key"]));
    var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);
    var claims = new[]
    {
        new Claim(ClaimTypes.NameIdentifier,user.Username),
        new Claim(ClaimTypes.Role,"apiuser")
    };
    var token = new JwtSecurityToken(_config["Jwt:Issuer"],
        _config["Jwt:Audience"],
        claims,
        expires: DateTime.Now.AddMinutes(15),
        signingCredentials: credentials);


    return new JwtSecurityTokenHandler().WriteToken(token);
}

public class UserModel
{
    public string Username { get; set; }
    public string Password { get; set; }
}

We've also added the following usings:

using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using Microsoft.IdentityModel.Tokens;

We're injecting an IConfiguration because we need some values from appSettings and other than that it's mostly copied code from the tutorial. As said, there's no verification of any credentials, we just generate a token and spit it out.

Now let's try it out in Postman by sending a POST to the new endpoint at https://localhost:44336/umbraco/api/TestApi/GenerateJwtToken, adding a username and password.

Success! We get a token that we can hopefully use in the GetAuthenticatedMessage call.

Going back to Postman, we can add a header to the GetAuthenticatedMessage request named Authorization and as the value we add Bearer, then a space and then the token we received from the GenerateJwtToken endpoint.

And as you can see in the response body, we do indeed get our message back, this time it's not lying to us: You need to be authenticated to see this message.. Correct!

And there you have it, JWT tokens demystified (for me at least 😅).

Create a plain dotnet, routed API controller in Umbraco

Sebastiaan Janssen — Mon, 07 Nov 2022 08:38:14 +0000

This is a very quick blog post, blink and you'll miss it! 😉

While building something the other day I suddenly had the need for a route that would output some JSON data. I didn't need anything from Umbraco, just some plain old (modern!) dotnet - yes this is for Umbraco 9+.

I thought I'd have to register routes in Startup.cs and that I'd have to add a route to ReservedPaths in appSettings.json, but.. to my surprise: none of that is needed, nice and easy and contained in 1 single .cs file.

So without further ado, here's the example:

using Microsoft.AspNetCore.Mvc;

namespace Cultiv.Controllers;

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class GreetMeController : ControllerBase
{
    [HttpGet]
    public ActionResult Get([FromQuery]string name)
    {
        var value = new MyModel
        {
            Introduction = "Hello",
            Name = string.IsNullOrWhiteSpace(name) ? "World" : name
        };

        return new JsonResult(value);
    } 
}

public class MyModel
{
    public string Introduction { get; set; }
    public string Name { get; set; }
}

The interesting part here is the Route attribute, where [controller] will be replaced with the controller name, GreetMe, so the route becomes api/GreetMe and the Get method is what will respond to any Get request coming in.

This results in a nice JSON string response with the proper application/json response header:

This is called attribute routing and you can do a LOT more with it, check out the Microsoft documentation for more information.

That's it, that's the post! Just wanted to save it here to my external brain so I can find it in the future, hopefully it will help someone else as well.

TIL: mime types and static assets in Umbraco

Sebastiaan Janssen — Fri, 21 Oct 2022 08:37:29 +0000

A few months ago I wrote a post about learnings from the Umbraco Discord that week and then.. it went quiet 😅

With the best of intentions to keep that series going, it turns out there's just not enough hours in the day! I have ideas though to open up the information from Discord more but that will have to be bit more long term.

In the mean time, we did go down a fun exploration path with Dean Leigh yesterday thinking about adding custom MIME types to Umbraco and overriding existing ones if needed.

This turned into a thread where explored the actual needs and some solutions.

`Program.cs` vs `Startup.cs`

First off, I understand the confusion, Umbraco 9 was built on .net 5 and that required us to have Startup.cs and Program.cs.

In .net 6, Microsoft consolidated the two into Program.cs and updated all of their documentation to that effect. We're not ready yet in Umbraco to do the same, so there will be some confusion for a while.

So for now, in Umbraco you're encouraged never to touch Program.cs and only ever make changes to Startup.cs.

Mime types

As it turns out, Dean's original question was about trying to figure out how to host and serve the new(-ish) avif format, an image format with really great compression.

Image credit: Jake Archibald

Since .net doesn't yet support avif and neither does ImageSharp, files of this type just didn't have a MIME type available and trying to use them would result in a 404 error.

I remembered seeing an example recently to help cache static assets. These are specifically listing file types that ImageSharp doesn't touch. If you added something like jpg in that list, the request would be cached very early and never hit the ImageSharp middleware.

Adding/changing MIME types is pretty similar to adding cache control headers, so I played with that code to see how far we could get.

As it turns out, I was trying my code on webp files first, changing their MIME type from image/webp to image/text to see if it would work. It didn't! I was close though and with some great help from my colleague Ronald I understood that I was only changing the MIME type for .net and then the next thing kicked in: ImageSharp. When ImageSharp sees a request for a webp file, it reads the metadata from the file and sets the MIME type (correctly!) back to image/webp. So after a bit of experimenting we came up with the following code:

⚡⚠️ danger danger, this messes with the default webp content type, don't use in production⚡⚠️

using Microsoft.AspNetCore.Http.Extensions;
using Microsoft.AspNetCore.StaticFiles;
using SixLabors.ImageSharp.Web;
using SixLabors.ImageSharp.Web.Middleware;
using Umbraco.Cms.Core.Composing;

public class ContentTypeComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        var contentTypeProvider = new FileExtensionContentTypeProvider();
        contentTypeProvider.Mappings[".webp"] = "image/text";

        builder.Services.Configure<StaticFileOptions>(options => options.ContentTypeProvider = contentTypeProvider);
        builder.Services.Configure<ImageSharpMiddlewareOptions>(options =>
        {
            var prepareResponseAsync = options.OnPrepareResponseAsync;
            options.OnPrepareResponseAsync = async (context) =>
            {
                var formatUtilities = context.RequestServices.GetRequiredService<FormatUtilities>();
                if (formatUtilities.TryGetExtensionFromUri(context.Request.GetDisplayUrl(), out var extension) &&
                    contentTypeProvider.TryGetContentType('.' + extension, out var contentType))
                {
                    context.Response.ContentType = contentType;
                }

                await prepareResponseAsync(context);
            };
        });
    }
}

Cool, that worked!

One caveat though, as you can see in the code above, this is updating the Mappings for an existing content type, and as we learned earlier, avif is not supported in .net yet and therefore there is no existing content type. We also don't have to think about ImageSharp since it doesn't support avif yet either.

So to make avif get a proper MIME type, the code needed to change a bit:

using Microsoft.AspNetCore.StaticFiles;
using Umbraco.Cms.Core.Composing;

public class ContentTypeComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        var contentTypeProvider = new FileExtensionContentTypeProvider();
        if (!contentTypeProvider.Mappings.ContainsKey(".avif"))
        {
            contentTypeProvider.Mappings.Add(".avif", "image/avif");
        }

        builder.Services.Configure<StaticFileOptions>(options => options.ContentTypeProvider = contentTypeProvider);
    }
}

Here we added the MIME type if the mapping doesn't yet exist, if it ever starts to exist in the future we assume it gets the correct mapping anyway.

Bonus

If you want to learn more about headers and CORS, my colleague Warren has a great Hack Make Do video on this topic as well!

Conclusion

And there we have it, now we can add a MIME type to any unknown file format and we learned at the same time how to override MIME types for ImageSharp. Plus.. now that we know how to hook into the ImageSharp middleware options, we could probably think of more fun things to do in there as well.

Debugging your custom website against the Umbraco source code

Sebastiaan Janssen — Fri, 30 Sep 2022 07:24:17 +0000

Imagine this scenario: you're weeks into building a new website in Umbrco and encounter a bug. You step into Umbraco's source code (available through SourceLink) and you learn what's going on. Even better you spot the problem and you have a good idea of how to fix it!

Now in the "olden days" (also known as the .NET Framework days) you would be able to do something like:

Clone the Umbraco source code
Find the problematic class and attempt a fix
Build Umbraco
Copy the dll and pdb files from that build output to your custom website
Wait for the site to recycle and observe if the bug is fixed
Or you could go back to the Visual Studio (VS) / Rider instance where the Umbraco source code is open and attach to the IIS / IISExpress that's running your custom website, set a few breakpoints and use the debugger to get closer to the problem you're experiencing

This workflow used to look a bit like this:

I've personally been doing this for very rapid debugging for years and it has served me very well in Umbraco versions 8 and below, also known as "Classic Umbraco" (thanks Marc Goodson!).

The big caveat here was that if you were to change your custom code in your custom website and do a build in VS/Rider, NuGet would make sure that those dlls that were built straight from the Umbraco source code (including your bug fix) will be overwritten with the officially released dlls for that Umbraco version. So after you build your custom site, you'd have to copy those back in to test your bugfix.

Umbraco 9+

Enter Umbraco versions 9 and above, or "Modern Umbraco" all tranformed to run on a new runtime, dotnet version 5/6/etc (the artist previously know as dotnet core).

The workflow used for .NET Framework does not and can not work any more. When a website is running, there's no way to overwrite dll files new ones, everything is locked. Even if we were to succeed, there's no automatic recyle of the website, so the site will probably just crash.

There is such a thing as "hot reload", which allows use to make code changes and, without building the solution, continuing to use our website. However, I believe that still actually does a build in the background and I don't know what voodoo is does to load the new code, but I doubt we're able to get anywhere near hooking into it. Hot reload is also very limited, it's pretty easy to make a change that's not supported by hot reload and you have to stop and start your site again anyway.

What also would not work was copying in the dll / pdb files when the website was not running. As with "Classic Umbraco", once you run the website it will build and copy the dll files from the official NuGet package back into the site and the code we update would be gone.

We explored different ways of debugging and fixing the Umbraco source code against a custom website in a recent UmbraCollab episode.

UmbraCollab is a weekly event where we find an interesting Umbraco related topic to work on and we try to see how far we can take it in 1 hour, with the help of anyone who wishes to join live. We run UmbraCollab in the voice/video channel on our Discord instance.

We eventually found a nice way of doing a similar type of rapid prototyping and debugging on "Modern Umbraco", with a quite pleasant way to set it up and run a debugger against our custom site.

As a bit of background, the Umbraco source code is a solution that contains many (VS/Rider)projects, and one of those projects is named Umbraco.Web.UI. This is really "just" a blank Umbraco website, like you would start building if you were to set up your own dotnet new Umbraco.

We found that we could add our custom website project as part of the Umbraco source solution. I know, right? 🤯

In VS/Rider, right-click on the solution and choose to add a project, you can choose an existing project (csproj file) that can live anywhere on your local machine, so in my example I choose D:\Temp\SourceDebug\MyProject\MyProject.cs

Now you should be able to run the MyProject project in the dropdown in Visual Studio:

Or in Rider:

"Magically" from here on in you can alter the Umbraco source code and debug the code, setting breakpoints where you need them. No more copying around dls and pdbs either.

The modern workflow looks a bit like this:

Pretty smooth huh? 😎

There were two problems we encountered but they don't always seem to happen:

You might have a bit of a clash with ModelsBuilder models if you use InMemoryAuto, so find the folder in UmbracoProject > umbraco > DATA > TEMP > InMemoryAuto and right-click on it to choose "Exclude" - this way it won't be part of the build
You might have to add two namespaces to your MyProject's Startup.cs: using Umbraco.Cms.Core.DependencyInjection; and using Umbraco.Extensions; (because: for some reason, when included in the Umbraco source solution, the <ImplicitUsings>enable</ImplicitUsings> directive in MyProject.csproj is not always recognized).

Caveats

There's two caveats to this approach:

Your IDE (Visual Studio, Rider, etc.) will update the umbraco.sln file with the reference to your custom project. If you're planning to contribute your updated code back to Umbraco using a pull request, make sure to revert the changes to umbraco.sln before you commit and push, then the team of reviewers doesn't have to remind you.
Likewise, your custom project's csproj file will now include a reference to the directory where you cloned Umbraco-CMS and if you had to exclude ModelsBuilder files, that will also have been added to the csproj file. If you want to keep your colleauges happy, don't commit those changes to source control either.

I always scan whatever changes I'm adding to source control (don't be the git add . person please, take some pride in what you commit!) so it's easy to revert these changes before committing.

Let me know if you have even more clever ways of doing this in "Modern Umbraco", I'm personally very much enjoying this new approach and it's making me nice and productive!

Umbraco Discord wrap-up week 18

Sebastiaan Janssen — Fri, 06 May 2022 07:59:03 +0000

Every week I realize what a wealth of information gets shared in the Umbraco Discord and the many things I might want to look up again later, so I've started keeping a list!

CORS

How to modify CORS on Umbraco netcore, asks Sean.

My teammate Paul has the answer:

services.Configure<UmbracoPipelineOptions>(opt => {
    opt.AddFilter(new UmbracoPipelineFilter("cors")
    {
        PostPipeline = app => app.UseCors(cors =>
        {
            cors.AllowAnyMethod()  // for example
                .AllowAnyHeader()  // for example
                .AllowAnyOrigin(); // for example
        })
    });
});

Should just be able to do this in configure services (or a composer etc)

Modelsbuilder

Heather made me check out Limbo Modelsbuilder:

While, by the way, Sean is plugging his upcoming Codegarden talk about building the Aardman website on Umbraco.

Heather notes that much of the Modelsbuilder functionality that was available in the v8 Visual Studio extension is now again available in this package.

Element types and tags

Søren blogged about bypassing (some) of our limitations when trying to use certain property editors in nested content / block editor.

While Lee also points out that his wonderful Contentment package can use the data from property editors like the Tags editors.

Lee also noted during UmbraCollab that Contentment already works with Umbraco 10, he has an alpha release out now!

UmbraCollab

As you may or may not know, every Thursday at 13:00 CET we get together on Discord and do a bit of mob programming. This week we tried to do some Umbraco 10 upgrades.

Paul kicked off with what was going to be an attempt to upgrade his Portfolio Starter Kit and Examine Content App to Umbraco 10. Turns out both of those "just" worked on v10 already, so there was really nothing to do, excellent!

Then I tried to upgrade my blog to v10 and ran into some problems, similar problems happened on a different test site I had laying around and it turns out I forgot to upgrade the sites to .NET 6 - after which everything just worked, smooth. Thanks Bjarke for the hint and for providing the updated docs.

The recording is on YouTube:

UmbraCollab - 5th May 2022 - YouTube

The Umbraco community come together on Discord to hack and collobrate on a problem on their lunch time every Thursday 12 - 1PM GMT UK

youtube.com

Redis

Gareth wrote a blog post about caching Umbraco content in Redis after getting some feedback.

Setting properties to read-only

Harry asked about making some properties read-only under certain conditions.

And Paul Seal reminds us of Marc Goodson's blogpost about his attempts at limiting editor access by language.

Vite

Dan Hammond has been on a journey this week to get Vite to load in the backoffice and eventually seems to have gotten there with a bit of help from Nathan and by orchestrating a big hack.

He notes:

In the loader:

const ready = $.prototype.ready;

let queued = [];
$.prototype.ready = function ( fn ) {
  queued.push( fn );
};

$.enableReady = function() {
  queued.forEach((x) => {
    ready.call(this, x);
  })

  $.prototype.ready = ready;
}

let script = document.createElement("script");
script.type = "module";
script.src = "/backoffice/src/main.ts";
document.getElementsByTagName('head')[0].appendChild(script);

In my Vite script:

if ( $.enableReady ) {
  $.enableReady()
}

Visual Studio code cleanup

Lastly, Matt Wise shared a useful link for those not yet using Rider.

Automatic code cleanup on saving a file is coming to Visual Studio at last.

That's a wrap!

Wow, that was a lot going on in just a single week! Hard to keep up.

As always, you're welcome to join us and collaborate on anything you're working on in Umbraco at the moment. Or just lurk, as you can see there's a lot to learn from.

UmbraCollab opportunity 💡

As a final note:

We are always looking for people to join us on UmbraCollab. Thursday at 13:00, strictly limited to one hours of collaborating on something. Topics can include:

working on a pull request
working on a new package
converting existing packages to a newer version
trying out new (or old) features in Umbraco

You drive the screen and we help you out with helpful (and sometimes completely useless) comments. Usually we get pretty far in an hour and most of all we all learn something new.

Tweet me, DMs are open 👋, if you would like to take the opportunity and share something interesting!