Tim Heuer

Another selfish tool–Endpoint for VS Code

2026-01-28T02:37:10Z

I recently was actually building a personal app that integrated with 5 different third-party APIs, each having different authentication requirements or API keys to navigate the calls. I normally would just use .http files and be done with it, but I’m a GUI person at heart and as much as I was iterating with the app and these services (across sandbox/prod environments too), navigating the single .http file just as raw text was getting frustrating for me honestly. I was already using the Rest Client for VS Code extension which is great and the absolute simplest and likely widely used. I tried a few other extensions in the marketplace but they have really shifted to be ‘enterprise’ and SaaS based and I just didn’t need all those capabilities or want a service.

So I just decided to have Copilot help me and iterate on a plan and implementation…and decided to call it “Endpoint” and here we are.

It’s basically a REST client, but biased hard toward *staying inside the editor* and keeping your requests portable.

What problem this is trying to solve (for me)

There are already a lot of ways to “test an endpoint.” This isn’t meant to be a hot take about existing tools. This is more like: what do I personally want when I’m iterating fast and gives me a structured way of seeing output?

For me the pain points are:

I want an API client that feels like part of VS Code: Same theme, same UX expectations, no “external app” vibe.
I want requests to be roaming with me, or shareable in the repo just like .http files: If a request is useful, I want it in source control not in a service.
I want multi-step flows to be easy: The classic “call login, grab token, call the real endpoint” loop.
I wanted some level of compatibility with the .http format because I do use multiple tools

Endpoint is my attempt at optimizing those loops for me.

But don’t `.http` files already do this?

Yep — and that’s actually part of the point. I like `.http` files because they’re **portable**, **diffable**, and **live well in source control**. If all you need is “a request in a file that I can run,” `.http` is a great answer and REST Client is a great simple tool!

Endpoint leans into that by supporting import/export so you can move between the file format and the GUI workflow. In other words: even if you don’t start in `.http`, you can end up there (and vice versa). Endpoint isn’t trying to replace that model; it’s a selfish tool for GUI lovers who want something around the same workflow and make it easier, intuitive, and graphical:

A native GUI for editing params/headers/auth/body without living in raw text all day
Collections + defaults (shared headers/auth/variables) so you don’t repeat yourself
Environments that are quick to switch (and don’t accidentally leak secrets into git)
Chaining + pre-requests for the auth/multi-step reality of modern APIs
Code snippets if you need bridge from “it works” to “ship it in the app”

So if you already have `.http` files you love, cool — keep them. Endpoint is me acknowledging that the file format is great, but I personally wanted fewer papercuts while iterating.

Why not just persist everything as `.http` all the time? Mostly because the GUI needs a structured model (headers on/off, auth type fields, body mode, collection defaults/inheritance, secret handling, etc.). You *can* represent a lot of that in text, but you quickly end up either losing fidelity or inventing extra conventions. I chose to persist a richer model for the day-to-day workflow, and then use import/export as the compatibility layer when you want the portable file representation.

What about other existing GUI tools?

Yep, there are a good set of ones out there that are incredibly rich. Some are mostly freemium models too though. And some may not be able to be used in certain environments because of organizational policies. These are all fantastic tools, but they didn’t work for my every need, so I just selfishly wanted my own flow…which I acknowledge may not work for anyone else’s need :-). But by all means, the ones out there are super popular, incredibly powerful, and do way more for advanced scenarios.

What Endpoint gives me (in practice)

At a high level, it’s a request builder + response viewer that stays inside VS Code. The part I care about isn’t the checklist of features — it’s that the whole loop (edit → send → inspect → tweak → repeat) happens without me leaving the editor.

The mental model is simple: Collections for grouped project scopes and saved requests, Environments for variables, and a simple split request/response view with the most important things at the surface.

The small set of things I reach for most:

Variables + `.env` support so I’m not hardcoding base URLs or keys (supports .env files, or stored in VS Code SecretStorage)
Repeatable/shared/inherited properties for headers and auth
Chaining / pre-requests for “login then use token” flows
Roaming saved collections across machines – even when I’m not wanting to persist these to team repo yet
Export/import for when I want to serialize for sharing broadly if needed

I’m still iterating, but those cover 90% of my day-to-day.

Summary

This isn’t meant to replace every API tool ever as I mentioned. Nearly every tool I create starts for extremely selfish reasons. It’s optimized for the thing I do the most: tight inner-loop iteration while already living in VS Code.

If you need heavyweight collaboration features, deep test scripting, or a bunch of external integrations, this isn’t going to be it and you might still prefer something else.

But if your primary pain is “I just want to hit this endpoint while I’m validating, and I don’t want to leave the editor and have the same editor UI,” then this has been a meaningful productivity boost for me and maybe for you.

Feel free to try it out and log issues as you face them using “Report Issue” in VS Code!

AI in My Developer Workflow: From Prompting to Planning

2026-01-27T17:37:50Z

When I first started using AI in my developer workflow, I treated it like a smarter search engine.

Short prompts. Minimal context. Very atomic asks. And usually in the editor as a comment, triggering the completions flow is where I operated!

“Write me a regex for X.”
“Why is this failing?”
“Convert this to C#.”

Sometimes it worked. Often it didn’t. And when it didn’t, my instinct was to tweak a word or two and try again, the same way I would refine a Google query. That mindset held me back longer than I realized.

Early Exploration: Terse Prompts, Terse Results

Those early days were mostly frustration disguised as curiosity. I was optimizing for speed, not clarity. I would fire off a one-liner, get something half right, then either patch it myself or throw it away.

The ‘early days’ is also funny to think about how fast things are moving. I’ll acknowledge that the models I was using as an early adopter also were not as advanced as they are as of this writing in January 2026, nor will be in a month, 2 months, 3 months from now! The breadth of models and their capabilities is one of the rapid accelerations in this space.

What I didn’t appreciate at the time was that I was giving the model no room to reason. I was asking for outcomes without offering intent. No constraints. No tradeoffs. No plan.

AI isn’t terrible at this, but it is also not where it shines. I was leaving a lot of capability on the table.

The Shift: Planning First, Prompting Second

The biggest unlock for me wasn’t a new model. It was planning. I saw my peers like Pierce Boggan really leverage a two-phased approach using custom prompts (what we called ‘chat modes’ earlier) around Planning and Implementation. Pierce shared some early iterations around how he did that and I found myself really starting to switch to these modes (here is what I used to use: Planning, Implementation).

Once I started explicitly asking the AI to plan before writing code, everything changed. Instead of jumping straight to implementation, I would ask for a high-level approach, assumptions, risks, tradeoffs, and open questions.

This became useful not just for greenfield projects, but especially for bigger features inside existing systems. The kind of work where you need to think about impact radius, backwards compatibility, and how something will age over time.

This planning mode is now built in to nearly every tool. There are some heavier-weight workflows like SpecKit and things that require some ‘constitution’ setup and if that’s for you, that’s great. Those also can be re-usable inputs to any planning mode as well. For me an open slate has been fine and I just iterate IN planning mode and ensure that I address any follow-ups

The real step change came when I started persisting those plans as an artifact and task list (again, before task-tracking was in any of the tools I used).

I now drop them into a /docs/ folder. Sometimes they are lightweight notes. Sometimes they look more like a product requirements document. Either way, they live alongside the code. That means they are reviewable, shareable, and reusable.

Treating that conversation as an artifact was not only a context-saving changer, but also a time one! Those documents also become prompts. I didn’t have to rely on memory sessions and instead could get back later and start prompting with “Let’s work on part 3 of the plan now” and Copilot could pick right up with all the context. When I come back days or weeks later, I can feed the plan back into the model and say, “Continue from here.” That continuity has been incredibly valuable. So when offered to ‘start implementation’ or save the plan…always opt to save the plan!

Agents and Longer-Lived Context

From there, moving into agents felt natural.

I have been starting many projects using Burke Holland’s Opus Agent, and it was a great on-ramp. What clicked for me was not just the output, but the structure.

Sub-agents handling focused tasks. Instructions that evolve as the project evolves. A clearer separation between thinking and doing. Instructions to also persist new-learnings for the benefit of later sessions. This part of the prompt can’t be stated enough how valuable it is. Here’s the snippet:

Each time you complete a task or learn important information about the project, you should update the `.github/copilot-instructions.md` or any `agent.md` file that might be in the project to reflect any new information that you've learned or changes that require updates to these instructions files.

That structure maps much more closely to how I actually work as a developer. Iterative. Layered. Occasionally opinionated.

Context helpers are also essential. I’ve found Context7 (who was a first mover in the MCP server context race) to be fantastic for my needs so far! It serves as part of the researcher in this custom agent fetching information about frameworks, documentation about guidelines, blog posts that might be helpful, and reasoning with all of that to provide me with some well-rounded options. Seriously, use it.

Sessions, State, and Knowing When to Start Fresh

Another habit I have had to learn is session management.

I now treat a new problem like opening a new terminal window. If I am switching domains, rethinking an approach, or starting a distinct feature, I open a new session.

That reset matters. It avoids dragging along stale assumptions and accidental context. State is powerful, but only when it is intentional.

Different Models for Different Jobs

I also no longer believe there is a single best model. This has really been where the massive advancements have taken place in my opinion. GPT was amazing, until Claude Sonnet 3.x came out, until Claude Sonnet 4.5 came out, until Claude Opus 4.5 came out, until Gemini Pro 3, etc, etc.

Right now, my personal defaults look like this:

Opus 4.5 for coding and deeper technical reasoning
Gemini Pro for UI exploration and visual-adjacent thinking
“-mini” variants at time for some speed needs

They have different strengths, and leaning into that has made the workflow feel more like a toolbox and less like a magic button. Your own mileage may vary depending on the tech, problem space, and tool you are using. Try them all is my advice and you’ll settle on one that works with your style, your tooling and your desired output you prefer. I focus on finding the one to help me complete the ‘job to be done’ versus any bias I have on whether it is good for any given framework I may be familiar with.

Debug inner-loop

I’ve also got a lot more comfortable with debugging with the Copilot in my inner-loop. If I have any error that wasn’t caught in build (where Copilot would normally see it and fix), or a UI that isn’t quite right, or an output that is wrong…I just copy paste that into that same fix session (or use a new one if a new problem) and sometimes just say “fix it.” Quite literally I’ve taken screenshots, pasted, said “fix it” and it does – interpreting the image, the issue, and scoping the fix. Amazing iterative process for most things! Heck I even pasted Apple App Store rejection notes into a new session “app got rejected, here was the notes” and BOOM with confidence it started to get to work Ah, I see where <appname> is violating this guideline, I’ll work on a fix… These moments make me smile every time.

An Honest Take: I Still Prefer a GUI

One thing worth saying out loud is that I still strongly prefer working in a GUI. Sorry, I’m just old I guess.

A lot of AI tooling momentum right now is centered around the CLI. Agents that live in terminals. Prompts piped through commands. Workflows that assume you want to live in a shell all day.

While I can do that, I do not particularly enjoy it. For me, the CLI experience is not intuitive.

I am far more effective inside environments like VS Code or Visual Studio, where I already live. I can review code visually and contextually. I can leverage other extensions alongside AI. I can navigate files, diffs, tests, logs, and resources in one place. I can reason about the project as a whole, not just a stream of text. That familiarity matters. AI works best for me when it is embedded into that environment, not when it pulls me out of it. When I am already thinking about a feature, a refactor, or a bug, I want the AI to meet me there rather than forcing a context switch just to interact with it. Easier for me to mentally see other context, relationship to my repo, quick diff reviewing, etc.

This also ties back to planning. Having plans, docs, and context living next to the code makes everything easier to review, validate, and evolve. The GUI is not just comfort. It is leverage.

I know plenty of developers feel the opposite, and that is great. This is just what works best for me. And I acknowledge just like my transition to using AI, my transition to using different methods of development will also evolve I’m sure. I’m personally just not seeing a huge benefit to moving to a CLI-only flow for what I do development on these days – I don’t need 10 terminal instances running at one time.

Acknowledging the Privilege

One thing I do not want to gloss over is that this workflow is enabled by paid plans. That matters. Not everyone can or should stack subscriptions just to experiment.

I am fortunate to be able to explore these tools deeply, and I try to stay conscious of that when talking about what has worked for me. I’m starting to pay more close attention to what feeds into my context window either on-purpose or accidental as I know it impacts token-based billing and just efficiency of the LLM as well.

Where I Have Landed

AI has not replaced how I build software. It has changed how I think while building it.

I plan more.
I am clearer about intent.
I have found a ‘peer’ to communicate with, not command. The more I can express as I would with a co-worker, the greater success I find.

And ironically, those improvements would still pay off even if the AI disappeared tomorrow.

That might be the biggest takeaway for me. The most valuable part of integrating AI into my workflow was not automation. It was becoming a more deliberate developer.

Adding environment vars to .NET Aspire services

2023-11-29T00:49:10Z

Have you heard about .NET Aspire yet? If not, go read, then maybe watch. It’s okay I’ll wait.

Ok, great now that you have some grounding, I’m going to share some tips time-to-time of things that I find delightful that may not be obvious. In this example I’m using the default .NET Aspire application template and added an ASP.NET Web API with enlisting into the orchestration. What does that mean exactly? Well the AppHost project (orchestrator) now has a reference to the project like so:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.WebApplication1>("webapplication1");

builder.Build().Run();

When I run the AppHost it launches all my services, etc. Yes this is a VERY simple case and only one service…I’m here to make a point, stay with me.

If in my service I add some Aspire components they may come with their own configuration information. Things like connection strings or configuration options for the components. A lot of times these will result in environment variables at deploy time that the components will read. You can see this if you run and inspect the environment variables of the app:

But what if I have a configuration/variable that I need to set that isn’t coming from a component? I want that to be a part of the application model so that the orchestrator puts things in the right places, but also deployment tooling is aware of my whole config needs. No problem, here’s a quick tip if you haven’t discovered it yet!

I want a config value in my app as MY_ENV_CONFIG_VAR…a very important variable. It is a value my API needs as you can see in this super important endpoint:

app.MapGet("/somerandomconfigvar", () =>
{
    var config = builder.Configuration.GetValue<string>("MY_ENV_CONFIG_VAR");
    return config;
});

How can I get this in my Aspire environment so the app model is aware, deployment manifests are aware, etc. Easy. In the AppHost change your AddProject line to add a WithEnvironment() call specifying the variable/value to set. Like this:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.WebApplication1>("webapplication1")
    .WithEnvironment("MY_ENV_CONFIG_VAR", "Hello world!");

builder.Build().Run();

Now when I launch the orchestrator runs all my services and adds them to the environment variables for that app:

And when I produce a deployment manifest, that information is stamped as well for deployment tools to reason with and set in their configuration way.

{
  "resources": {
    "webapplication1": {
      "type": "project.v0",
      "path": "..\\WebApplication1\\WebApplication1.csproj",
      "env": {
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true",
        "MY_ENV_CONFIG_VAR": "Hello world!"
      },
      "bindings": {
        "http": {
          "scheme": "http",
          "protocol": "tcp",
          "transport": "http"
        },
        "https": {
          "scheme": "https",
          "protocol": "tcp",
          "transport": "http"
        }
      }
    }
  }
}

Pretty cool, eh? Anyhow, just a small tip to help you on your .NET Aspire journey.

Anatomy of a .NET devcontainer

2023-10-25T17:47:10Z

Recently, the .NET team released a starter Codespaces definition for .NET. There is a great narrated overview of this and the benefit, uses, etc. by the great James Montemagno you can watch here:

Unbelievable Instant .NET Development Setup. It is available when you visit https://github.com/codespaces and you can start using it immediately.

Codespaces are built off of the devcontainer mechanism, which allows you to define the environment in a bunch of different ways using container images or just a devcontainer image. I won’t go through all the options you can do with devcontainers, but will share the anatomy of this and what I like about it.

NOTE: If you don’t know what Development Containers are, you can read about them here https://containers.dev/

Throughout this post I’ll be referring to snippets of the definition but you can find the FULL definition here: github/dotnet-codespaces.

Base Image

Let’s start with the base image. This is the starting point of the devcontainer, the OS, and pre-configurations built-in, etc. You can use a Dockerfile definition or a pre-defined container image. I think if you have everything bundled nicely in an existing container image in a registry, start there. Just so happens, .NET does this and has nice images with the SDK already in them, so let’s use that!

{
    "name": ".NET in Codespaces",
    "image": "mcr.microsoft.com/dotnet/sdk:8.0",
    ...
}

This uses the definition from our own container images defined here: https://hub.docker.com/_/microsoft-dotnet-sdk/. Again this allows us a great/simple starting point.

Features

In the devcontainer world you can define ‘features’ which are like little extensions someone else has done to make it easy to add/inject into the base image. One aspect of adding things can be done through pre/post scripts, but if someone has created a ‘feature’ in the devcontainer world, this makes it super easy as you delegate that setup to this feature owner. For this image we’ve added a few features:

{
    "name": ".NET in Codespaces",
    "image": "mcr.microsoft.com/dotnet/sdk:8.0",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {},
        "ghcr.io/devcontainers/features/github-cli:1": {
            "version": "2"
        },
        "ghcr.io/devcontainers/features/powershell:1": {
            "version": "latest"
        },
        "ghcr.io/azure/azure-dev/azd:0": {
            "version": "latest"
        },
        "ghcr.io/devcontainers/features/common-utils:2": {},
        "ghcr.io/devcontainers/features/dotnet:2": {
            "version": "none",
            "dotnetRuntimeVersions": "7.0",
            "aspNetCoreRuntimeVersions": "7.0"
        }
    },
    ...
}

So here we see that the following are added:

Docker in docker – helps us use other docker-based features
GitHub CLI – why not, you’re using GitHub so this adds some quick CLI-based commands
PowerShell – an alternate shell that .NET developers love
AZD – the Azure Developer CLI which helps with quick configuration and deployment to Azure
Common Utilities – check out the definition for more info here
.NET features – even though we are using a base image, in this case .NET 8, there may be additional runtimes we need so we can use this to bring in more. In this case this is needed for one of our extensions customizations that need the .NET 7 runtime.

This enables the base image to append additional functionality when this devcontainer is used.

Extras

You can configure more extras through a few more properties like customizations (for environments) and pre/post commands.

Customizations

The most common used configuration of this section is to bring in extensions for VS Code. Since Codespaces default uses VS Code, this is helpful and also carries forward if you use VS Code locally with devcontainers (which you can do!).

{
    "name": ".NET in Codespaces",
    ...
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-vscode.vscode-node-azure-pack",
                "github.vscode-github-actions",
                "GitHub.copilot",
                "GitHub.vscode-github-actions",
                "ms-dotnettools.vscode-dotnet-runtime",
                "ms-dotnettools.csdevkit",
                "ms-dotnetools.csharp"
            ]
        }
    },
    ...
}

In this snippet we see that some VS Code definitions will be installed for us to get started quickly:

Azure Extensions – a set of Azure extensions to help you quickly work with Azure when ready
GitHub Actions – view your repo’s CI/CD activity
Copilot – AI-assisted code development
.NET Runtime – this helps with any runtime acquisitions needed by activity or other extensions
C#/C# Dev Kit – extensions for C# development to make you more productive in the editor

It’s a great way to configure your dev environment to be ready to start when you use devcontainers without spending time hunting down extensions again.

Commands

Additionally you can do some post-create commands that may be used to warm-up environments, etc. An example here:

{
    "name": ".NET in Codespaces",
    ...
    "forwardPorts": [
        8080,
        8081
    ],
    "postCreateCommand": "cd ./SampleApp && dotnet restore",
    ...
}

This is used to get the sample source ready to use immediately by restoring dependencies or other commands, in this case running the restore command on the sample app.

Summary

I am loving devcontainers. Every time I work on a new repository or anything I’m now looking first for a devcontainer to help me quickly get started. For example, I recently explored a Go app/repo and don’t have any of the Go dev tools on my local machine and it didn’t matter. The presence of a devcontainer allowed me to immediately get started with the repo with the dependencies and tools and let me get comfortable. And portable as I can navigate from machine-to-machine with Codespaces and have the same setup needed by using devcontainers!

Hope this little insight helps. Check out devcontainers and if you are a repo owner, please add one to your Open Source project if possible!

Monitor your GitHub Actions in Visual Studio

2023-08-07T22:59:59Z

I LOVE GitHub Actions! I’ve written about this a lot and how I’ve ‘seen the light’ with regard to ensuring CI/CD is a part of any/every project from the start. That said I’m also a HUGE Visual Studio fan/user. I like having everything as much as possible at my fingertips in my IDE and for most basic things not have to leave VS to do those things. Because of this I’ve created GitHub Actions for Visual Studio extension that installs right into Visual Studio 2022 and gives you immediate insight into your GitHub Actions environment.

Like nearly every one of my projects it starts as completely selfish reasons and tailored to my needs. I spend time doing this in some reserved learning time and the occasional time where my family isn’t around and/or it’s raining and I can’t be on my bike LOL. That said, it may not meet your needs, and that’s okay.

With that said, let me introduce you to this extension…

How to launch it

First you’ll need to have a project/solution open that is attached to GitHub.com and you have the necessary permissions to view this information. The extension looks for GitHub credentials to use interacting with your Windows Credential manager. From VS Solution Explorer, right-click on a project or solution and navigate to the “GitHub Actions” menu item. This will open a new tool window and start querying the repository and actions for more information. There is a progress indicator that will show when activity is happening. Once complete you’ll have a new tool window you can dock anywhere and it will show a few things for you, let’s take a look at what those are.

Options

There are a small set of options you can configure for the extension:

The following can be set:

Max Runs (Default=10): this is the maximum number of Workflow Runs to retrieve
Refresh Active Jobs (Default=False): if True, this will refresh the Workflow Runs list when any job is known to be in-progress
Refresh Interval (Default=5): This is a number in seconds you want to poll for an update on in-progress jobs.

Managing Workflows

Aside from viewing the list there are a few other things you can do using the extension:

Hover over the Run to see details of the final conclusion state, how it was triggered, the total time for the run, and what GitHub user triggered the run
If a run is in-progress, right-click on the run and you can choose to Cancel, which will attempt to send a cancellation to stop the run at whatever step it is in
On the steps nodes you can double-click or right-click and choose to view logs. This will launch your default browser to the location of the step log for that item
From the Workflows list, you can right-click on a name of a Workflow and choose “Run Workflow” which will attempt to signal to run the start a run for that Workflow

Managing Secrets

Secrets right now are limited to Repository Secrets only. This is due to a limitation the Octokit library this extension uses. If you are using Environment Secrets you will not be able to manage them from here.

Otherwise:

From the Repository Secrets node you can right-click and Add Secret which will launch a modal dialog to supply a name/value for a new secret. Clicking save will persist this to your repo and refresh the list.
From an existing secret you can double-click it or right-click and choose ‘Edit’ and will launch the same modal dialog but just enables you to edit the value only.
To delete a secret, right-click and choose delete. This is irreversible, so be sure you want to delete!

Get Started and Log Issues

To get started, you simply can navigate to the link on the marketplace and click install or use the Extension Manager in Visual Studio and search for “GitHub Actions” and install it. If you find any issues, the source is available on my GitHub at timheuer/GitHubActionsVS but also would appreciate that you could log an Issue if you find it not working for you. Thanks for trying it out and I hope it is helpful for you as it is for me.

Creating a VS Code editor extension

2023-06-30T00:52:27Z

As I’ve been working more with Visual Studio Code lately, I wanted to explore more about the developer experience and some of the more challenging areas around customization. VS Code has a great extensibility model and a TON of UI points for you to integrate. In the C# Dev Kit we’ve not yet had the need to introduce any custom UI in any views or other experiences that are ‘pixels’ on the screen for the user…pretty awesome extensibility. One area that doesn’t have default UI is the non-text editors. Something that you want to do fully custom in the editor space. For me, I wanted to see what this experience was so I went out to create a small custom editor. I chose to create a ResX editor for the simplest case as ResX is a known-schema based structure that could easily be serialized/de-serialized as needed.

NOTE: This is not an original idea. There are existing extensions that do ResX editing in different ways. With nearly every project that I set out with, it starts as a learning/selfish reasons…and also selfish scope. Some of the existing ones had expanded features I felt unnecessary and I wanted a simple structure. They are all interesting and you should check them out. I’m no way claiming to be ‘best’ or first-mover here, just sharing my learning path.

With that said, I’m pleased with what I learned and the result, which is an editor that ‘fits in’ with the VS Code UX and achieves my CRUD goal of editing a ResX file:

With that, here’s what I’ve learned a bit…

Custom Editors and UI

There are a lot of warnings in the Custom Editor API docs of making sure you really need a custom editor, but point to the value of what they can provide for previewing/WYSIWYG renderings of documents. But they point to the fact that you will likely be using a webview and thus be fully responsible for your UI. In the end you are owning the UI that you are drawing. For me, I’m not a UI designer, so I rely on others/toolkits to do a lot of heavy lifting. The examples I saw out there (and oddly enough the custom editor sample) don’t match the VS Code UX at all and I didn’t like that. I actually found it odd that the sample took such an extreme approach to the editor (cat paw drawings) rather than show a more realistic data-focused scenario on a known file format.

Luckily the team provides the Webview UI Toolkit for Visual Studio, a set of components that match the UX of VS Code and adhere to the theming and interaction models. It’s excellent and anyone doing custom UI in VS Code extensions should start using this immediately. Your extension will feel way more professional and at home in the standard VS Code UX. My needs were fairly simple and I wanted to show the ResX (which is XML format) in a tabular format. The toolkit has a data-grid that was perfect for the job…mostly. But let’s start with the structure.

Most of the editor is in a provider (per the docs) and that’s where you implement a CustomTextEditorProvider which provides a register and resolveCustomTextEditor commands. Register does what you think, register’s your editor into the ecosystem, using the metadata from package.json about what file types/languages will trigger your editor. Resolve is where you start providing your content. It provides you with a Webview panel where you put your initial content. Mine was a simple grid:

private _getWebviewContent(webview: vscode.Webview) {
  const webviewUri = webview.asWebviewUri(vscode.Uri.joinPath(this.context.extensionUri, 'out', 'webview.js'));
  const nonce = getNonce();
  const codiconsUri = webview.asWebviewUri(vscode.Uri.joinPath(this.context.extensionUri, 'media', 'codicon.css'));
  const codiconsFont = webview.asWebviewUri(vscode.Uri.joinPath(this.context.extensionUri, 'media', 'codicon.ttf'));

  return /*html*/ `
            <!DOCTYPE html>
            <html lang="en">
              <head>
                <meta charset="UTF-8">
                <meta name="viewport" content="width=device-width, initial-scale=1.0">
                <meta
                  http-equiv="Content-Security-Policy"
                  content="default-src 'none'; img-src ${webview.cspSource} https:; script-src 'nonce-${nonce}'; style-src ${webview.cspSource} 'nonce-${nonce}'; style-src-elem ${webview.cspSource} 'unsafe-inline'; font-src ${webview.cspSource};"
                />
                <link href="${codiconsUri}" rel="stylesheet" nonce="${nonce}">
              </head>
              <body>
                <vscode-data-grid id="resource-table" aria-label="Basic" generate-header="sticky" aria-label="Sticky Header"></vscode-data-grid>
                <vscode-button id="add-resource-button">
                  Add New Resource
                  <span slot="start" class="codicon codicon-add"></span>
                </vscode-button>
                <script type="module" nonce="${nonce}" src="${webviewUri}"></script>
              </body>
            </html>
          `;
}
}

This serves as the HTML ‘shell’ and then the actual interaction is via the webview.js you see being included. Some special things here or just how it includes the correct link to the js/css files I need but also notice the Content-Security-Policy. That was interesting to get right initially but it’s a recommendation solid meta tag to include (otherwise console will spit out warnings to anyone looking). The webview.js is basically any JavaScript I needed to interact with my editor. Specifically this uses the registration of the Webview UI Toolkit and converts the resx to json and back (using the npm library resx). Here’s a snippet of that code in the custom editor provider that basically updates the document to JSON format as it changes:

private async updateTextDocument(document: vscode.TextDocument, json: any) {

  const edit = new vscode.WorkspaceEdit();

  edit.replace(
    document.uri,
    new vscode.Range(0, 0, document.lineCount, 0),
    await resx.js2resx(JSON.parse(json)));
  return vscode.workspace.applyEdit(edit);
}

So that gets the essence of the ‘bones’ of the editor that I needed. Once I had the data then a function in the webview.js can ‘bind’ the data to the vscode-data-grid supplying the column names + data easily and just set as the data rows quickly (lines 20,21):

function updateContent(/** @type {string} **/ text) {
    if (text) {

        var resxValues = [];

        let json;
        try {
            json = JSON.parse(text);
        }
        catch
        {
            console.log("error parsing json");
            return;
        }

        for (const node in json || []) {
            if (node) {
                let res = json[node];
                // eslint-disable-next-line @typescript-eslint/naming-convention
                var item = { Key: node, "Value": res.value || '', "Comment": res.comment || '' };
                resxValues.push(item);
            }
            else {
                console.log('node is undefined or null');
            }
        }

        table.rowsData = resxValues;
    }
    else {
        console.log("text is null");
        return;
    }
}

And the vscode-data-grid generates the rows, sticky header, handles the scrolling, theming, responding to environment, etc. for me!

Now I want to edit…

Editing in the vscode-data-grid

The default data-grid does NOT provide editing capabilities unfortunately and I really didn’t want to have to invent something here and end up not getting the value from all the Webview UI Toolkit. Luckily some in the universe also tackling the same problem. Thankfully Liam Barry was at the same time trying to solve the same problem and helped contribute what I needed. It works and provides a simple editing experience:

Now that I can edit can I delete?

Deleting items in the grid

Maybe you made an error and you want to delete. I decided to expose a command that can be invoked from the command palette but also from a context menu. I specifically chose not to put an “X” or delete button per-row…it didn’t feel like the right UX. Once I created the command (which basically gets the element and then the _rowData from the vscode-data-grid element (yay, that was awesome the context is set for me!!). Then I just remove it from the items array and update the doc. The code is okay, but the experience is simple exposing as a right-click context menu:

This is exposed by enabling the command on the webview context menu via package.json – notice on line 2 is where it is exposed on the context menu and the conditions of which it is exposed (a specific config value and ensuring that my editor is the active one):

"menus": {
  "webview/context": [
    {
      "command": "resx-editor.deleteResource",
      "when": "config.resx-editor.experimentalDelete == true && activeCustomEditorId == 'resx-editor.editor'"
    }
  ]
...
}

Deleting done, now add a new one!

Adding a new item

Obviously you want to add one! So I want to capture input…but don’t want to do a ‘form’ as that doesn’t feel like the VS Code way. I chose to use a multi-input method using the command area to capture the flow. This can be invoked from the button you see but also from the command palette command itself.

Simple enough, it captures the inputs and adds a new item to the data array and the document is updated again.

Using the default editor

While custom editors are great, there may be times you want to use the default editor. This can be done by doing “open with” on the file from Explorer view, but I wanted to provide a quicker method from my custom editor. I added a command that re-opens the active document in the text editor:

let openInTextEditorCommand = vscode.commands.registerCommand(AppConstants.openInTextEditorCommand, () => {
  vscode.commands.executeCommand('workbench.action.reopenTextEditor', document?.uri);
});

and expose that command in the editor title context menu (package.json entry):

"editor/title": [
{
  "command": "resx-editor.openInTextEditor",
  "when": "activeCustomEditorId == 'resx-editor.editor' && activeEditorIsNotPreview == false",
  "group": "navigation@1"
}
...
]

Here’s the experience:

Helpful way to toggle back to the ‘raw’ view.

Using the custom editor as a previewer

But what if you are in the raw view and want to see the formatted one? This may be common for standard formats where users do NOT have your editor set as default. You can expose a preview mode for yours and similarly, expose a button on the editor to preview it. This is what I’ve done here in package.json:

"editor/title": [
...
{
  "command": "resx-editor.openPreview",
  "when": "(resourceExtname == '.resx' || resourceExtname == '.resw') && activeCustomEditorId != 'resx-editor.editor'",
  "group": "navigation@1"
}
...
]

And the command that is used to open a document in my specific editor:

let openInResxEditor = vscode.commands.registerCommand(AppConstants.openInResxEditorCommand, () => {

    const editor = vscode.window.activeTextEditor;

    vscode.commands.executeCommand('vscode.openWith',
        editor?.document?.uri,
        AppConstants.viewTypeId,
        {
            preview: false,
            viewColumn: vscode.ViewColumn.Active
        });
});

Now I’ve got a different ways to see the raw view, preview, or default structured custom view.

Nice!

Check out the codez

As I mentioned earlier this is hardly an original idea, but I liked learning, using a standard UX and trying to make sure it felt like it fit within the VS Code experience. So go ahead and give it an install and play around. It is not perfect and comes with the ‘works on my machine’ guarantee.

The code is out there and linked in the Marketplace listing for you.

Make your VS Code extension more helpful

2023-06-26T17:14:04Z

Whenever I work on something new, I like to make sure I try to better understand the tech and the ecosystem around it. With the launch of the C# Dev Kit, I had to dive deeper into understanding some things about how VS Code extensions work, and get dirtier with TypeScript/JavaScript more than usual that my ‘day job’ required. As a part of how I learn, I build. So I went and built some new extensions. Nearly all of my experiments are public on my repos, and all come with disclaimers that they usually are for completely selfish reasons (meaning they may not help anyone else but me – or just learning) or may not even be original ideas really. I only say that because you may know a lot of this already.

As a part of this journey I’ve loved the VS Code extensibility model and documentation. It really is great for 99% of the use cases (the remaining 1% being esoteric uses of WebView, some of the VS Code WebView UI Toolkit, etc). And one thing I’ve come to realize is the subtleties of making your VS Code extension a lot more helpful to your consumers in the information, with very little effort – just some simple entries in package.json in fact. Here were some that I wasn’t totally aware of (they are in the docs) mostly because my `yo code` starting point doesn’t emit them. Nearly all of these exist to help people understand your extension, discover it, or interact with YOU better. And they are simple!

The Manifest

First, make sure you understand the extension manifest is not just a package.json for node packages. It represents metadata for your Marketplace and some interaction with VS Code itself!

It’s just some snippet of text, but powers a few experiences…here are some I’ve noticed provide some added Marketplace and product value.

Repository

Sounds simple, but can be helpful if your extension is Open Source. The repository just surfaces a specific link in your listing directly to your repository.

"repository": {
  "type": "git",
  "url": "https://github.com/timheuer/resx-editor"
}

Simple enough, you specify a type and to the root of your repo.

Bugs

You want people to log issues right? This attribute powers the ‘Report Issue’ capability within VS Code itself:

To add this you simply put a URL to the issues collector of your project. Could be anything really, but if it is a GitHub repo then your users will be able to directly log an issue from within VS Code. If it is not, then the URL of your issues collector (e.g., Jira, Azure DevOps) will be displayed here in link format.

"bugs": {
  "url": "https://github.com/timheuer/resx-editor/issues"
}

This is super helpful for your users and I think a requirement!

Q&A

By default if you publish to the Visual Studio Marketplace, then you get an Q&A tab for your extension. People can come here and start asking questions. I personally think the experience is not great here right now, as the publisher is the sole respondent, the conversation isn’t threaded, etc. But you can change that.

"qna": "https://github.com/timheuer/resx-editor/issues"

By adding this, the Q&A link in the marketplace will now direct people to your specific link here rather than bifurcate your Q&A discussions in marketplace and your chosen place. This can be GitHub Issues, GitHub Discussions, some other forum software, whatever. It provides a good entry point so that you don’t have to monitor yet another Q&A portion for your product.

Keywords

Yes you have categories (which are specific words that the Marketplace knows about), but you can also have keywords (up to 5). This is helpful when you basically want to add some searchable context/content that might not be in your title or brief description.

"keywords": [
  "resx",
  "resw",
  "resource",
  "editor",
  "viewer"
],

You can only have 5 so tune them well, but don’t leave these out. They also display in the marketplace listing.

Badges

Who doesn’t love a good badge to show build status or versioning! One small delighter for the nerds among us is the Marketplace/manifest support this URL format from a set of approved badge providers. Adding this in your manifest:

"badges": [
  {
    "url": "https://img.shields.io/visual-studio-marketplace/v/timheuer.resx-editor?label=VS%20Code%20Marketplace&color=brightgreen&logo=visualstudiocode",
    "href": "https://marketplace.visualstudio.com/items?itemName=TimHeuer.resx-editor",
    "description": "Current Version"
  },
  {
    "url": "https://github.com/timheuer/resx-editor/actions/workflows/build.yaml/badge.svg",
    "href": "https://github.com/timheuer/resx-editor/actions/workflows/build.yaml",
    "description": "Build Status"
  }
]

now shows these by default in your Marketplace listing:

Maybe a bit ‘extra’ as my daughter would say, but I think it adds a nice touch.

Snippets

If you are a code provider or a custom editor you may want to add some snippets. Your extension can directly contribute them with your other functionality.

"snippets": [
  {
    "language": "xml",
    "path": "./snippet/resx.json"
  }
]

Then when your extension is installed these are just a part of it and you don’t need to provide a ‘snippet only’ pack of sorts.

Menus

If you are doing custom things, you likely already know about contributing menus and commands. But did you know that commands appear in the command palette by default? Perhaps you don’t want that as your command is context specific: only when a certain file type is open, a specific editor is in view, etc. So you’ll want to hide them by default in the command pallette using the ‘when’ clause like in lines 5 and 11 here. I want to never show one in the command palette (when:false) and the other only certain conditions when a specific view is open.

"menus": {
  "webview/context": [
    {
      "command": "resx-editor.deleteResource",
      "when": "config.resx-editor.experimentalDelete == true && webviewId == 'resx-editor.editor'"
    }
  ],
  "commandPalette": [
    {
      "command": "resx-editor.deleteResource",
      "when": "false"
    }
  ]
}

This enables the commands to be surfaced where you want like custom views, context menus, etc. without them showing as an ‘anytime’ available command.

Summary

There is a lot more you can do and of course the most important thing is providing a useful extension (heck, even if only to you). But these are some really simple and subtle changes I noticed in my learning that I think more extension authors should take advantage of! Hope this helps!

Writing an OpenAI plugin for ChatGPT using ASP.NET Core

2023-06-17T16:50:17Z

Well it was all about AI at Microsoft Build this year for sure…lots of great discussions and demos around GitHub Copilot, OpenAI, Intelligent Apps, etc. I’ve been heavily relying on GitHub Copilot recently as I’ve been spending more time in writing VS Code extensions and I’m not as familiar with TypeScript. Having that AI assistant with me *in the editor* has been amazing.

One of the sessions at Build was the keynote from Scott Guthrie where VP of Product, Amanda Silver, demonstrated building an OpenAI plugin for ChatGPT. You can watch that demo starting at this timestamp as it was a part of the “Next generation AI for developers with the Microsoft Cloud” overall keynote. It takes a simple API about products from the very famous Contoso outlet and exposes an API about products. Amanda then created a plugin using Python and showed the workflow of getting this to work in ChatGPT. So after a little prompting on Twitter and some change of weekend plans, I wanted to see what it would take to do this using ASP.NET Core API development. Turns out it is pretty simple, so let’s dig in!

Working with ChatGPT plugins

A plugin in this case help connect the famous ChatGPT experience to third-party applications (APIs). From the documentation:

These plugins enable ChatGPT to interact with APIs defined by developers, enhancing ChatGPT's capabilities and allowing it to perform a wide range of actions. For example, here is the Savvy Trader ChatGPT plugin in action where I can ask it investment questions and it becomes the responsible source for providing the data/answers to my natural language inquiry:

A basic plugin is a definition of a manifest that describe how ChatGPT should interact with the third-party API. It’s a contract between ChatGPT, the plugin, and the API specification, using OpenAPI. That’s it simply. Could your existing APIs ‘just work’ as a plugin API? That’s something you’d have to consider before just randomly exposing your whole API surface area to ChatGPT. It makes more sense to be intentional about it and deliver a set of APIs that are meaningful to the AI model to look and receive a response. With that said, we’ll keep on the demo/simple path for now.

For now the ChatGPT plugins require two sides: a ChatGPT Plus subscription to use them (plugins now available to all Plus subscribers) and to develop you need to be on the approved list, for which you must join the waitlist to develop/deploy a plugin (as of the date of this writing).

Writing the API

Now the cool thing for .NET developers, namely ASP.NET Core developers is writing your API doesn’t require anything new for you to learn…it’s just your code. Can it be enhanced with more? Absolutely, but as you’ll see here, we are literally keeping it simple. For ours we’ll start with the simple ASP.NET Core Web API template in Visual Studio (or `dotnet new webapi –use-minimal-apis`). This gives us the simple starting point for our API. We’re going to follow the same sample as Amanda’s so you can delete all the weather forecast sample information in Program.cs. We’re going to add in some sample fake data (products.json) which we’ll load as our ‘data source’ for the API for now. We’ll load that up first:

// get some fake data
List<Product> products = JsonSerializer.Deserialize<List<Product>>(File.ReadAllText("./Data/products.json"));

Observe that I have a Product class to deserialize into, which is pretty simple class that maps to the sample data…not terribly important for this reading.

Now we want to have our OpenAPI definition crafted a little, so we’re going to modify the Swagger definition a bit. The template already includes Swashbuckle package to help us generate the OpenAPI specification needed…we just need to provide it with a bit of information. I’m going to modify this to provide the title/description a bit better (otherwise by default it uses a set of project names you probably don’t want).

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo() { Title = "Contoso Product Search", Version = "v1", Description = "Search through Contoso's wide range of outdoor and recreational products." });
});

Now we’ll add an API for products to query our data and expose that to OpenAPI definition:

app.MapGet("/products", (string? query = null) =>
{
    if (query != null) { 
        return products?.Where(p => p.Name.Contains(query, StringComparison.OrdinalIgnoreCase) || 
        p.Description.Contains(query, StringComparison.OrdinalIgnoreCase) || 
        p.Category.Contains(query, StringComparison.OrdinalIgnoreCase) ); 
    }

    return products;
})
.WithName("GetProducts")
.WithDescription("Get a list of products")
.WithOpenApi();

That’s it. You can see the highlighted lines where we further annotate the endpoint for the OpenAPI specification. Now we have our API working and it will produce an OpenAPI spec by default at {host}/swagger/v1/swagger.yaml for us. Note that you can further modify this location if you want providing a different route template in the Swagger config.

Now let’s move on to exposing this for ChatGPT plugins!

Exposing the API to ChatGPT

Plugins are enabled in ChatGPT by first providing a manifest that informs ChatGPT about what the plugin is, where the API definitions are, etc. This is requested at a manifest located at {yourdomain}/.well-known/ai-plugin.json. This is a well-known location and it is looking for a response that conforms to the schema. Here are some advanced scenarios for authentication for a plugin, but we’ll keep it simple and expose this for all with no auth needed. Details about the plugin manifest can be found here: ai-plugin.json manifest definition. It’s a pretty simple file. You probably will need a logo for your plugin of course – maybe use AI to generate that for you ;-).

There are a few ways you can expose this. You can simply add a wwwroot folder, enable static files and drop the file in wwwroot\.well-known\ai-plugin.json. To do that in your API project create the wwwroot folder, then create the .well-known folder (with the ‘.’) and put your ai-plugin.json file in that location. If you go this approach you’ll want to ensure in your Program.cs you enable static files:

app.UseStaticFiles();

After you have all this in place you’ll need to enable CORS policy so that the ChatGPT can access your API correctly. First you will need to enable CORS (line 1 in your builder) and then configure a policy for the ChatGPT domain (line 6 in the app):

builder.Services.AddCors();

...


app.UseCors(policy => policy
    .WithOrigins("https://chat.openai.com")
    .AllowAnyMethod()
    .AllowAnyHeader());

Now our API will be callable form the ChatGPT app.

Using Middleware to configure the manifest

As mentioned the static files approach for exposing the manifest is the simplest…but that’s no fun right? We are developers!!! As I was looking at this myself, I put together a piece of ASP.NET middleware to help me configure it. You can use the static files approach (in fact you’ll have to do that with your logo if hosting at the same place as your API) for sure, but just in case here’s a middleware approach that I put together. First you’ll install the package TimHeuer.OpenAIPluginMiddleware from NuGet. Once you’ve done that now you’ll add the service and tell the pipeline to use it. First add it to the services of the builder (line 1) and then tell the app to use the middleware (line 15):

builder.Services.AddAiPluginGen(options =>
{
    options.NameForHuman = "Contoso Product Search";
    options.NameForModel = "contosoproducts";
    options.LegalInfoUrl = "https://www.microsoft.com/en-us/legal/";
    options.ContactEmail = "noreply@microsoft.com";
    options.LogoUrl = "/logo.png";
    options.DescriptionForHuman = "Search through Contoso's wide range of outdoor and recreational products.";
    options.DescriptionForModel = "Plugin for searching through Contoso's outdoor and recreational products. Use it whenever a user asks about products or activities related to camping, hiking, climbing or camping.";
    options.ApiDefinition = new Api() { RelativeUrl = "/swagger/v1/swagger.yaml" };
});

...

app.UseAiPluginGen();

This might be overkill, but now your API will respond to /.well-known/ai-plugin.json automatically without having to use the static files manifest approach. This comes in handy for any dynamic configuration of your manifest (and was the reason I created it).

Putting it together

With all this in place, now we go to ChatGPT (remember, need a Plus subscription) and add our plugin. Since ChatGPT is a public site and we haven’t deployed our app yet to anywhere, we need to be able to have ChatGPT call it. Visual Studio Dev Tunnels to the rescue! If you haven’t heard about these yet, it is the fastest and most convenient way to get a public tunnel to your dev machine right from within Visual Studio! In fact, this scenario is exactly what Dev Tunnels are for! In our project we’ll create a tunnel first, and make it available to everyone (ChatGPT needs public access). In VS first create a tunnel, you can do that easily from the ‘start’ button of your API in the toolbar:

and then configure the options:

More details on these options are available at the documentation for Dev Tunnels, but these are the options I’m choosing. Now once I have that the tunnel will be activated and when I run the project from within Visual Studio, it will launch under the Dev Tunnel proxy:

You can see my app running, responding to the /.well-known/ai-plugin.json request and serving it from a public URL. Now let’s make it known to ChatGPT…

First navigate to https://chat.openai.com and ensure you choose the GPT-4 approach then plugins:

Once there you will see the option to specify plugins in the drop-down and then navigate to the plugin store:

Click that and choose ‘Develop your own plugin’ where you will be asked to put in a URL. This is where your manifest will respond to (just need the root URL). Again, because this needs to be public, Visual Studio Dev Tunnels will help you! I put in the URL to my dev tunnel and click next through the process (because this is development you’ll see a few things about warnings etc):

After that your plugin will be enabled and now I can issue a query to it and watch it work! Because I’m using Visual Studio Dev Tunnels I can also set a breakpoint in my C# code and see it happening live, inspect, etc:

A very fast way to debug my plugin before I’m fully ready for deployment!

Sample code

And now you have it. Now you could actually deploy your plugin to Azure Container Apps for scale and you are ready to let everyone get recommendations on backpacks and hiking shoes from Contoso! I’ve put all of this together (including some Azure deployment infrastructure scripts) in this sample repo: timheuer/openai-plugin-aspnetcore. This uses the middleware that I created for the manifest. That repo is located at timheuer/openai-plugin-middleware and I’d love to hear comments on the usefulness here. There is some added code in that repo that dynamically changes some of the routes to handle the Dev Tunnel proxy URL for development.

Hope this helps see the end to end of a very simple plugin using ASP.NET Core, Visual Studio, and ChatGPT with plugins!

Contain your excitement for ASP.NET on Azure

2023-01-27T23:14:15Z

Okay, so I won’t quit my day job in favor of trying to come up with a witty title for a blog post. But this is one thing that I’m proud to see our team deliver: one of the fastest ways to get your ASP.NET app to a container service on Azure (or elsewhere) without having to know what containers are or learn new things. No really!

Cloud native

Well if you operate in the modern web world you’ve heard this term ‘cloud native’ before. And everyone has an opinion on what it means. I’m not here to pick sides and I think it means a lot of different things. One commonality it seems that most can agree on is that one aspect is of deploying a service to the cloud as ‘cloud native’ is to leverage containers. If you aren’t familiar with containers, go read here: What is a container? It’s a good primer on what they are technically but also some benefits. Once you educate yourself you’ll be able to declare yourself worthy to nod your head in cloud native conversations and every once in a while throw out comments like “Yeah, containers will help here for us.” or something like that. Instantly you will be seen as smart and an authority and the accolades will start pouring in. But then you may actually have to do something about it in your job/app. Hey don’t blame me, you brought this on yourself with those arrogant comments! Have no fear, Visual Studio is here to help!

Creating and deploying a container

If you haven’t spent time working with containers, you will be likely introduced to new concepts like Docker, Dockerfile, compose, and perhaps even YAML. In creating a container, you typically need to have a definition of what your container is, and generally this will be a Dockerfile. A typical Docker file for a .NET Web API looks like this:

#See https://aka.ms/customizecontainer to learn how to customize your debug container and how Visual Studio uses this Dockerfile to build your images for faster debugging.

FROM mcr.microsoft.com/dotnet/aspnet:7.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:7.0 AS build
WORKDIR /src
COPY ["CommerceApi.csproj", "."]
RUN dotnet restore "./CommerceApi.csproj"
COPY . .
WORKDIR "/src/."
RUN dotnet build "CommerceApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "CommerceApi.csproj" -c Release -o /app/publish /p:UseAppHost=false

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "CommerceApi.dll"]

You can see a few concepts here that you’d have to understand and that’s not the purpose of this post. You’d then need to use Docker to build this container image and also to ‘push’ it to a container registry like Azure Container Registry (ACR). For a developer this would mean you’d likely have Docker Desktop installed that brings these set of tools to you locally to execute within your developer workflow. As you develop your solution, you’ll have to keep your Dockerfile updated if it involves more projects, version changes, path changes, etc. But what if you just have a simple service, you’ve heard about containers and you just want to get it to a container service as fast as possible and simple. Well, in Visual Studio we have you covered.

Publish

Yeah yeah, ‘friends don’t let friends…’ – c’mon let people be (more on that later). In VS we have a great set of tools to help you rapidly get your code to various deployment endpoints. Since containers are ‘the thing’ lately as of this writing we want to help you remove concepts and get their fast as well…in partnership with Azure. Azure has a new service launched last year called Azure Container Apps (ACA), a managed container environment that helps you scale your app. It’s a great way to get started in container deployments easily and have manageability and scale. Let me show you how we help you get to ACA quickly, from your beloved IDE, with no need for a Dockerfile or other tools. You’ll start with your ASP.NET Web project and start from the Publish flow (yep, right-click publish). From their choose Azure and notice Azure Container Apps right there for you:

After selecting that Visual Studio (VS) will help you either select existing resources that your infrastructure team helped setup for you or, if you’d like and have access to create them, create new Azure resources all from within VS easily without having to go to the portal. You can then select your ACA instance:

And then the container registry for your image:

Now you’ll be presented with an option on how to build the container. Notice two options because we’re nice:

If you still have a Dockerfile and want to go that route (read below) we enable that for you as well. But the first option is leveraging the .NET SDK that you already have (using the publish targets for the SDK). Selecting this option will be the ‘fast path’ to your publishing adventure.

Then click finish and you’re done, you now have a profile ready to push a container image to a registry (ACR), then to a container app service (ACA) without having to create a Docker file, learn a new concept or have other tools. Click publish and you’ll see the completed results and you will now be able to strut back into your manager’s office/cube/open space bean bag and say Hey boss, our service is all containerized and in the cloud ready to scale…where’s my promo?

VS has helped with millions of cloud deployments every month whether they be to VMs, PaaS services, Web Deploy to on-metal cloud-hosted machines, and now easily to container services like ACA. It’s very helpful and fast, especially for those dev/test scenarios as you iterate on your app with others.

Leveraging continuous integration and deployment (CI/CD)

But Tim, friends don’t let friends right-click publish! Pfft, again I say, do what makes you happy and productive. But also, I agree ;-). Seriously though I’ve become a believer in CI/CD for EVERYTHING I do now, no matter the size of project. It just raises the confidence of repeatable builds and creates an environment of collaboration better for other things. And here’s the good thing, VS is going to help you bootstrap your efforts here easily as well – EVEN WITH CONTAINERS! Remember that step where we selected the SDK to build our container? Well if your VS project is within a GitHub repository (free for most cases these days, you should use it!), we’ll offer to generate an Actions workflow, which is GitHub’s CI/CD system:

In choosing a CI/CD workflow, the CI system (in this case GitHub Actions) needs to know some more information: where to deploy, some credentials to use for deployment, etc. The cool thing is even in CI, Visual Studio will help you do all of this setup including retrieving and setting these values as secrets on your repo! Selecting this option would result in this summary for you:

And the resulting workflow in an Actions YAML file in your project:

name: Build and deploy .NET application to container app commerceapp
on:
  push:
    branches:
    - main
env:
  CONTAINER_APP_CONTAINER_NAME: commerceapi
  CONTAINER_APP_NAME: commerceapp
  CONTAINER_APP_RESOURCE_GROUP_NAME: container-apps
  CONTAINER_REGISTRY_LOGIN_SERVER: XXXXXXXXXXXX.azurecr.io
  DOTNET_CORE_VERSION: 7.0.x
  PROJECT_NAME_FOR_DOCKER: commerceapi
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout to the branch
      uses: actions/checkout@v3
    - name: Setup .NET SDK
      uses: actions/setup-dotnet@v1.8.0
      with:
        include-prerelease: True
        dotnet-version: ${{ env.DOTNET_CORE_VERSION }}
    - name: Log in to container registry
      uses: azure/docker-login@v1
      with:
        login-server: ${{ env.CONTAINER_REGISTRY_LOGIN_SERVER }}
        username: ${{ secrets.timacregistry_USERNAME_F84D }}
        password: ${{ secrets.timacregistry_PASSWORD_F84D }}
    - name: Build and push container image to registry
      run: dotnet publish -c Release -r linux-x64 -p:PublishProfile=DefaultContainer -p:ContainerImageTag=${{ github.sha }} --no-self-contained -p:ContainerRegistry=${{ env.CONTAINER_REGISTRY_LOGIN_SERVER }} -bl
    - name: Upload binlog for investigation
      uses: actions/upload-artifact@v3
      with:
        if-no-files-found: error
        name: binlog
        path: msbuild.binlog
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
    - name: Azure Login
      uses: azure/login@v1
      with:
        creds: ${{ secrets.commerceapp_SPN }}
    - name: Deploy to containerapp
      uses: azure/CLI@v1
      with:
        inlineScript: >
          az config set extension.use_dynamic_install=yes_without_prompt

          az containerapp registry set --name ${{ env.CONTAINER_APP_NAME }} --resource-group ${{ env.CONTAINER_APP_RESOURCE_GROUP_NAME }} --server ${{ env.CONTAINER_REGISTRY_LOGIN_SERVER }} --username ${{ secrets.timacregistry_USERNAME_F84D }} --password ${{ secrets.timacregistry_PASSWORD_F84D }}

          az containerapp update --name ${{ env.CONTAINER_APP_NAME }} --container-name ${{ env.CONTAINER_APP_CONTAINER_NAME }} --resource-group ${{ env.CONTAINER_APP_RESOURCE_GROUP_NAME }} --image ${{ env.CONTAINER_REGISTRY_LOGIN_SERVER }}/${{ env.PROJECT_NAME_FOR_DOCKER }}:${{ github.sha }}
    - name: logout
      run: >
        az logout

Boom! So now you CAN use right-click publish and still get started with CI/CD deploying to the cloud! Strut right back into that office: Hey boss, I took the extra step and setup our initial CI/CD workflow for the container service so the team can just focus on coding and checking it in…gonna take the rest of the week off.

Cool, but I have advanced needs…

Now, now I know there will be always cases where your needs are different, this is too simple, etc. and YOU ARE RIGHT! There are limitations to this approach which we outlined in our initial support for the SDK container build capabilities. Things like customizing your base container image, tag names, ports, etc. are all easily customizable in your project file as they feed into the build pipeline, so we have you covered on this type of customization. As your solution grows and your particular full microservices needs get more complex, you may outgrow this simplicity…we hope that means your app is hugely successful and profits are rolling in for your app! You’ll likely grow into the Dockerfile scenarios and that’s okay…you’ll have identified your needs and have already setup your starting CI/CD workflow that you can progressively also grow as needed. We will continue to listen and see about ways we can improve this capability as developers like you give us feedback!

Summary

Our goal in Visual Studio is to help you be productive with a range of tasks. Moving to ‘cloud native’ can be another thing that your team has to worry about and as you start your journey (or perhaps looking to simplify a bit) VS aims to be your partner there and continue to help you be productive in getting your code to the cloud quickly with as much friction removed from your normal workflow. Here’s a few links to read more in more corporate speak about these capabilities:

Thanks for reading!

GitHub Composite Actions are fast way to templatize workflows

2021-12-17T18:49:16Z

I’ve had a love/hate relationship with CI/CD for a long while ever since I remember it being a thing. In those early days the ‘tools’ were basically everyone’s homegrown scripts, batch files, random daemon hosts, etc. Calling something a workflow was a stretch. It was for that reason I just wasn’t a believer, it was just too ‘hard’ for the average dev. I, like many, would build from my machine and direct deploy or copy over to file shares (NOTE: LOTS of people still do this). Well the tools have gotten WAY better across the board from many different vendors and your options for great tools exist. I’ve been privileged to work with Damian Brady and Abel Wang to educate me on the ways of CI/CD a bit. I know Damian has a mantra about right-click publish, but that only made me want to make it simpler for devs.

NOTE: Did you know that for most projects in .NET working in VS you can use right-click Publish to generate a CI/CD workflow for you, further reducing the complexity?

Well, I’m a believer now and I make it part of my mission to improve the tool experience for .NET devs and also look to convince/advocate for .NET developers to use CI/CD even in the smallest of projects. I’ve honed my own workflows to now I truly just worry about development…releases just take care of themselves. It’s glorious and frees so much time. I go out of my way now when I see friend’s projects who are on GitHub but not using Actions, for example. Recently I was working with Mads Kristensen on some things and asked him if he’d consider using Actions. And in a few minutes I submitted a first PR to one of his projects showing how simple it was. I started from using my own `dotnet new workflow` tool as not all project types support the right-click Publish—>Actions work Visual Studio has done yet. This helps get started with the basics.

In a few back/forth with Mads he wanted to encapsulate more…the files were too busy for him LOL. Enter composite Actions (or technically composite run steps). This was my chance to look into these as I hadn’t really had a need yet. You should read the docs, but my lay explanation is that composite run steps enable you to basically templatize some of your steps into a single encapsulation…and VERY simply.

Let’s look at one example with Mads’ desires. Mads’ projects are usually Visual Studio extensibility projects and require a few things to build more than just the .NET SDK. In this particular instance Mads needed .NET SDK, NuGet, and MSBuild to be setup. No problem, I started out with this, because duh, why not:

  # prior portion of jobs removed for brevity
  steps:
    - name: Setup dotnet
      uses: actions/setup-dotnet@v1.9.0
      with:
        dotnet-version: 6.0.x

    - name: Setup MSBuild
      uses: microsoft/setup-msbuild@v1.1

    - name: Setup NuGet
      uses: NuGet/setup-nuget@v1.0.5

But wanting less text, we discussed and I encapsulated these three in one single step using a new composite action. Creating a composite action is simple and enables you to deploy it in a few ways. First you can just keep these in your own repo itself without having to release anything, etc. This is helpful when yours are very repo-specific and nobody is sharing them across org/repos. Let’s look at the above and how we might encapsulate this. I still want to enable SDK version input to start so need an input parameter for that. So in the repo I’ll create two new folders in the .github/workflows folder, creating a new path called ./github/workflows/composite/bootstrap-dotnet and then place a new action.yaml file in that directory. My action.yaml file looks like this:

# yaml-language-server: $schema=https://json.schemastore.org/github-action.json
name: 'Setup .NET build dependencies'
description: 'Sets up the .NET dependencies of MSBuild, SDK, NuGet'
branding:
  icon: download
  color: purple
inputs:
  dotnet-version:
    description: 'What .NET SDK version to use'
    required: true
    default: 6.0.x
  sdk:
    description: 'Setup .NET SDK'
    required: false
    default: 'true'
  msbuild:
    description: 'Setup MSBuild'
    required: false
    default: 'true'
  nuget:
    description: 'Setup NuGet'
    required: false
    default: 'true'
runs:
  using: "composite"
  steps:
    - name: Setup dotnet
      if: inputs.sdk == 'true'
      uses: actions/setup-dotnet@v1.9.0
      with:
        dotnet-version: ${{ inputs.dotnet-version }}

    - name: Setup MSBuild
      if: inputs.msbuild == 'true' && runner.os == 'Windows'
      uses: microsoft/setup-msbuild@v1.1

    - name: Setup NuGet
      if: inputs.nuget == 'true'
      uses: NuGet/setup-nuget@v1.0.5

Let’s break it down. Composite actions still have the same setup as other custom actions enabling you to have branding/name/description/etc. as well as inputs as I’ve defined starting at line 6. I can then use these inputs in later steps (line 27/30). As you can see this action basically is a template for other steps that use other actions…simple!!! Now in the primary workflow for the project it looks like this:

# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
name: "PR Build"

on: [pull_request]
      
jobs:
  build:
    name: Build 
    runs-on: windows-2022
      
    steps:
    - uses: actions/checkout@v2

    - name: Setup .NET build dependencies
      uses: ./.github/workflows/composite/bootstrap-dotnet
      with:
        nuget: 'false'

Notice the path to the workflow itself using the new folder structure (line 14). Now when this workflow runs it will bring this composite action in and also run it’s steps…beautiful. If the action is more generic and you want to move it out of the repo you can do that. In fact in this one we did just that and you can see it at timheuer/bootstrap-dotnet and be able to use it just like any other action in your setup. An example of changed like the above is as simple as:

# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
name: "PR Build"

on: [pull_request]

jobs:
  build:
    name: Build 
    runs-on: windows-2022
      
    steps:
    - uses: actions/checkout@v2

    - name: Setup .NET build dependencies
      uses: timheuer/bootstrap-dotnet@v1
      with:
        nuget: 'false'

Done! What’s also great is because this still is a legit GitHub Action you can publish it on the marketplace for others to discover and use (hence the branding). Here is this one we just demonstrated above in the marketplace:

So that’s a simple example of truly a template/merge of other existing actions. But can you use this method to create a custom action that just uses script for example, like PowerShell? YES! Let’s take another one of these examples that uploads the VSIX from our project to the Open VSIX gallery. Mads was using a PowerShell script that does his upload for him, so I’m copying that into a new composite action and making some inputs and then he can use it. Here’s the full composite action:

# yaml-language-server: $schema=https://json.schemastore.org/github-action.json
name: 'Publish to OpenVSIX Gallery'
description: 'Publishes a Visual Studio extension (VSIX) to the OpenVSIX Gallery'
branding:
  icon: upload-cloud
  color: purple
inputs:
  readme:
    description: 'Path to readme file'
    required: false
    default: ''
  vsix-file:
    description: 'Path to VSIX file'
    requried: true
runs:
  using: "composite"
  steps:
    - name: Publish to Gallery
      id: publish_gallery
      shell: pwsh
      run: |
        $repo = ""
        $issueTracker = ""

        # If no readme URL was specified, default to "<branch_name>/README.md"
        if (-not "${{ inputs.readme }}") {
          $readmeUrl = "$Env:GITHUB_REF_NAME/README.md"
        } else {
          $readmeUrl = "${{ inputs.readme }}"
        }

        $repoUrl = "$Env:GITHUB_SERVER_URL/$Env:GITHUB_REPOSITORY/"

        [Reflection.Assembly]::LoadWithPartialName("System.Web") | Out-Null
        $repo = [System.Web.HttpUtility]::UrlEncode($repoUrl)
        $issueTracker = [System.Web.HttpUtility]::UrlEncode(($repoUrl + "issues/"))
        $readmeUrl = [System.Web.HttpUtility]::UrlEncode($readmeUrl)

        # $fileNames = (Get-ChildItem $filePath -Recurse -File)
        $vsixFile = "${{ inputs.vsix-file }}"
        $vsixUploadEndpoint = "https://www.vsixgallery.com/api/upload"

        [string]$url = ($vsixUploadEndpoint + "?repo=" + $repo + "&issuetracker=" + $issueTracker + "&readmeUrl=" + $readmeUrl)
        [byte[]]$bytes = [System.IO.File]::ReadAllBytes($vsixFile)
             
        try {
            $webclient = New-Object System.Net.WebClient
            $webclient.UploadFile($url, $vsixFile) | Out-Null
            'OK' | Write-Host -ForegroundColor Green
        }
        catch{
            'FAIL' | Write-Error
            $_.Exception.Response.Headers["x-error"] | Write-Error
        }

You can see it is mostly a PowerShell script and has the inputs (line 6). And here it is in use in a project:

# other steps removed for brevity in snippet
  publish:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v2

      - name: Download Package artifact
        uses: actions/download-artifact@v2
        with:
          name: RestClientVS.vsix

      - name: Upload to Open VSIX
        uses: timheuer/openvsixpublish@v1
        with:
          vsix-file: RestClientVS.vsix

Pretty cool when your custom action is a script like this and you don’t need to do any funky containers, or have a node app that just launches pwsh.exe or stuff like that. LOVE IT! Here’s the repo for this one to see more: timheuer/openvsixpublish.

This will definitely be the first approach I consider when needing other simple actions for my projects or others. The simplicity and flexibility in ‘templatizing’ some steps is really great!

Hope this helps!

Limited Edition Custom .NET Cycling Jersey

2021-11-12T22:20:17Z

Well with the release of .NET 6, lots of excitement around the platform and me being the nerd I am with a love for cycling, it’s time to open up for another round of ordering for the highly exclusive limited edition .NET Cycling Kit (jersey and bib shorts).

Last year I had created these using the .NET Foundation assets and in accordance with the brand guidelines for the .NET project (did you know we had a branding guidelines?! Me neither, but now you do). Well, we’re opening it up for an exclusive another round (this is round 3) and probably the last (famous last words).

Here’s the details:

These are high-quality race-fit cycling kits…yes they are not cheap…nor is the quality.
These are race-fit, not ‘club fit’ so they are meant to fit tighter and in riding position
Sizing: Eliel Cycling Sizing Guide (for context I am 5’9” [175cm] and ~195lbs [88.5kg] and I prefer a Large top and Large bib shorts)
These are all 100% custom made-to-order – there is no ‘stock’ for immediate ship
For patience, upon store closing these will take 10-12 weeks of production – must be patient :-)
They are custom, sales final, no returns
They look awesome and are comfortable
You will be the envy of all cyclists who are .NET developers that didn’t get one
I make NO money on this
Microsoft makes no money on this
Microsoft has nothing to do with this
There is no telemetry collected on the kit

So how do you get one? Simple, click here: .NET Cycling Kit (Round 3) – you order direct from the manufacturer in California and pay direct to them. Please read the site and details clearly and as well for EU ordering.

If you have any questions about these, the best place to ask is ping me on Twitter @timheuer for questions that I may be able to answer on sizing or otherwise. I would love to see more .NET cyclists with their kits in the wild worldwide.

Forcing a failure in GitHub Actions based on a condition

2021-04-30T17:38:58Z

Last night I got tweeted at asking me how one could halt a CI workflow in GitHub Actions on a condition. This particular condition was if the code coverage tests failed a certain coverage threshold. I’m not a regular user of code coverage tools like Coverlet but I went Googling for some answers and oddly did not find the obvious answer that was pointed out to me this morning. Regardless the journey to discover an alternate means was interesting to me so I’ll share what I did that I feel is super hacky, but works and is a similar method I used for passing some version information in other workflows.

First, the simple solution for if you are using Coverlet and want to fail a build and thus a CI workflow is to use the MSBuild integration option and then you can simply use:

dotnet test /p:CollectCoverage=true /p:Threshold=80

I honestly felt embarrassed that I didn’t find this simple option, but oh well, it is there and is definitely the simplest option if you can use this option. But there you have it. When used in an Actions workflow if the threshold isn’t met, this will fail that step and you are done.

Creating your condition to inspect

But let’s say you need to fail for a different reason or in this example here, you couldn’t use the MSBuild integration and instead are just using the VSTest integration with a collector. Well, we’ll use this code coverage scenario as an example but the key step here is focusing on how to fail a step. Your condition may be anything but I suspect it is usually based on some previous step’s output or value. Well first, if you are relying on previous steps values, be sure you understand the power of using outputs. This is I think the best way to kind of ‘set state’ of certain things in steps. A step can do some things and either in the Action itself set an Output value, or in the workflow YAML you can do this as well using a shell command and calling the ::set-output method. Let’s look at an example…first the initial step (again using our code coverage scenario):

- name: Test
  run: dotnet test XUnit.Coverlet.Collector/XUnit.Coverlet.Collector.csproj --collect:"XPlat Code Coverage"

This basically will produce an XML output ‘report’ that contains the values we want to extract. Namely it’s in this snippet:

<?xml version="1.0" encoding="utf-8"?>
<coverage line-rate="0.85999999999" branch-rate="1" version="1.9" timestamp="1619804172" lines-covered="15" lines-valid="15" branches-covered="8" branches-valid="8">
  <sources>
    <source>D:\</source>
  </sources>
  <packages>
    <package name="Numbers" line-rate="1" branch-rate="1" complexity="8">
      <classes>

I want the line-rate value (line 2) in this XML to be my condition…so I’m going to create a new Actions step to extract the value by parsing the XML using a PowerShell cmdlet. Once I have that I will set the value as the output of this step for later use:

- name: Get Line Rate from output
  id: get_line_rate
  shell: pwsh  
  run: |
    $covreport = get-childitem -Filter coverage.cobertura.xml -Recurse | Sort-Object -Descending -Property LastWriteTime -Top 1
    Write-Output $covreport.FullName
    [xml]$covxml = Get-Content -Path $covreport.FullName
    $lineRate = $covxml.coverage.'line-rate'
    Write-Output "::set-output name=lineRate::$lineRate"

As you can see in lines 2 and 9 I have set a specific ID for my step and then used the set-output method to write a value to an output of the step named ‘lineRate’ that can be later used. So now let’s use it!

Evaluating your condition and failing the step manually

Now that we have our condition, we want to fail the run if the condition evaluates a certain way…in our case if the code coverage line rate isn’t meeting our threshold. To do this we’re going to use a specific GitHub Action called actions/github-script which allows you to run some of the GitHub API directly in a script. This is great as it allows us to use the core library which has a set of methods for success and failure! Let’s take a look at how we combine the condition with the setting:

- name: Check coverage tolerance
  if: ${{ steps.get_line_rate.outputs.lineRate < 0.9 }}
  uses: actions/github-script@v3
  with:
    script: |
        core.setFailed('Coverage test below tolerance')

Okay, so we did a few things here. First we are defining this step as executing the core.setFailed() method…that’s specifically what this step will do, that’s it…it will fail the run with a message we put in there. *BUT* we have put a condition on the step itself using the if condition checking. In line 6 we are executing the setFailed function with our custom message that will show in the runner log. On line 2 we have set the condition for if this step even runs at all. Notice we are using the ID of a previous step (get_line_rate) and the output parameter (lineRate) and then doing a quick math check. If this condition is met, then this step will run. If the condition is NOT met, this step will not run, but also doesn’t fail and the run can continue. Observe that if the condition is met, our step will fail and the run fails:

If the condition is NOT met the step is ignored, the run continues:

Boom, that’s it!

Summary

This was just one scenario but the key here is if you need to manually control a fail condition or otherwise evaluate conditions, using the actions/github-script Action is a simple way to do a quick insertion to control your run based on a condition. It’s quick and effective for some scenarios where your steps may not have natural success/fail exit codes that would otherwise fail your CI run. What do you think? Is there a better/easier way that I missed when you don’t have clear exit codes?

Hope this helps someone!

Adding approval workflow to your GitHub Action

2020-12-16T22:37:24Z

One of the biggest things that I’ve wanted (and have heard others) when adopting GitHub Actions is the use of some type of approval flow. Until now (roughly the time of this writing) that wasn’t possible easily in Actions. The concept of how Azure Pipelines does it is so nice and simple to understand in my opinion and a lot of the attempts by others using various Actions stitched together made it tough to adopt. Well, announced at GitHub Universe, reviewers is now in Beta for Actions customers!!! Yes!!! I spent some time setting up a flow with an ASP.NET 5 web app and Azure as my deployment to check it out. I wanted to share my write-up in hopes it might help others get started quickly as well. First I’ll acknowledge that this is the simplest getting started you can have and your workflows may be more complex, etc. If you’d like to have a primer and see some other updates on Actions, be sure to check out Chris Patterson’s session from Universe: Continuous delivery with GitHub Actions. With that let’s get started!

Setting things up

First we’ll need a few things to get started. These are things I’m not going to walk through here but will explain briefly what/why it is needed for my example.

An Azure account – I’m using this sample with Azure as my deployment because that’s where I do most of my work. You can get a free Azure account as well and do exactly this without any obligation.
Set up an Azure App Service resource – I’m using App Service Linux and just created it using basically all the defaults. This is just a sample so those are fine for me. I also created these using the portal to have everything setup in advance.
I added one Application Setting to my App Service called APPSERVICE_ENVIRONMENT so I could just extract a string noting which environment I was in and display it on the home page.
In your App Service create a Deployment Slot and name it “staging” and choose to clone the main service settings (to get the previous app setting I noted). I then changed the app setting value for this deployment slot.
Download the publish profile for each your production and staging instances individually and save those somewhere for now as we’ll refer back to them in the next step.
I created an ASP.NET 5 Web App using the default template from Visual Studio 2019. I made some code changes in the Index.cshtml to pull from app settings, but otherwise it is unchanged.
I used the new Git features in Visual Studio to quickly get my app to a repository in my GitHub account and enabled Actions on that repo.

That’s it! With those basics set up I can get started with the next steps of building out the workflow. I should note that the steps I’m outlining here are free for GitHub public repositories. For private repositories you need to be a GitHub Enterprise Server customer. Since my sample is public I’m ready to go!

Environments

The first concept is Environments. These are basically a separate segmented definition of your repo that you can associate secrets and protection rules with. This is the key to the approval workflow as one of the protection rules is reviewers required (aka approvers). The first thing we’ll do is set up two environments: staging and production. Go to your repository settings and you’ll see a new section called Environments in the navigation.

To create an environment, click the New Environment button and give it a name. I created one called production and one called staging. In each of these you can do things independently like secrets and reviewers. Because I’m a team of one person my reviewer will be me, but you could set up others like maybe a build engineer for staging approval deployment and a QA team for production deployment. Either way click the Required reviewers checkbox and add yourself at least and save protection rule.

NOTE: This area may expand more to further protection rules but for now it is reviewers or a wait delay. GitHub indicates others may be in the future.

Now we’ll add some secrets. With Environments, you can have independent secrets for each environment. Maybe you want to have different deployment variables, etc. for each environment, this is where you could do it. For us, this is specifically what we’ll use the different publish profiles for. Remember those profiles you downloaded earlier, now you’ll need them. In the staging environment create a new secret named AZURE_PUBLISH_PROFILE and paste in the contents of your staging publish profile. Then go to your production environment settings and do the same using the same secret name and use the production publish profile you downloaded earlier. This allows our workflow to use environment-specific secret settings when they are called, but still use the same secret name…meaning we don’t need AZURE_PUBLISH_PROFILE_STAGING naming as we’ll be marking the environment in the workflow and it will pick up secrets from that environment only (or the repo if not found there – you can have a hierarchy of secrets effectively).

Okay we’re done setting up the Environment in the repo…off to set up the workflow!

Setting up the workflow

To get me quickly started I used my own template so I could `dotnet new workflow` in my repo root using the CLI. This gives me a strawman to work with. Let’s build out the basics, we’re going to have 3 jobs: build, deploy to staging, deploy to prod. Let’s get started. The full workflow is in my repo for this post, but I’ll be extracting snippets to focus on and show relevant pieces here.

Build

For build I’m using my standard implementation of restore/build/publish/upload artifacts which looks like this (with some environment-specific keys):

jobs:
  build:
    name: Build
    if: github.event_name == 'push' && contains(toJson(github.event.commits), '***NO_CI***') == false && contains(toJson(github.event.commits), '[ci skip]') == false && contains(toJson(github.event.commits), '[skip ci]') == false
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET Core SDK ${{ env.DOTNET_CORE_VERSION }}
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: ${{ env.DOTNET_CORE_VERSION }}
    - name: Restore packages
      run: dotnet restore "${{ env.PROJECT_PATH }}"
    - name: Build app
      run: dotnet build "${{ env.PROJECT_PATH }}" --configuration ${{ env.CONFIGURATION }} --no-restore
    - name: Test app
      run: dotnet test "${{ env.PROJECT_PATH }}" --no-build
    - name: Publish app for deploy
      run: dotnet publish "${{ env.PROJECT_PATH }}" --configuration ${{ env.CONFIGURATION }} --no-build --output "${{ env.AZURE_WEBAPP_PACKAGE_PATH }}"
    - name: Publish Artifacts
      uses: actions/upload-artifact@v1.0.0
      with:
        name: webapp
        path: ${{ env.AZURE_WEBAPP_PACKAGE_PATH }}

Notice this job is ‘build’ and ends with uploading some artifacts to the job. That’s it, the core functionality is to build/test this and store the final artifacts.

Deploy to staging

Next job we want is to deploy those bits to staging environment, which will be our staging slot in our Azure App Service we set up before. Here’s the workflow job definition snippet:

  staging:
    needs: build
    name: Deploy to staging
    environment:
        name: staging
        url: ${{ steps.deploy_staging.outputs.webapp-url }}
    runs-on: ubuntu-latest
    steps:
    # Download artifacts
    - name: Download artifacts
      uses: actions/download-artifact@v2
      with:
        name: webapp

    # Deploy to App Service Linux
    - name: Deploy to Azure WebApp
      uses: azure/webapps-deploy@v2
      id: deploy_staging
      with:
        app-name: ${{ env.AZURE_WEBAPP_NAME }}
        publish-profile: ${{ secrets.AZURE_PUBLISH_PROFILE }}
        slot-name: staging

In this job we download the previously published artifacts to be used as our app to deploy. Observe a few other things here:

I’ve declared that this job ‘needs’ the ‘build’ job to start. This ensures a sequence workflow. If build job fails, this doesn’t start.
I’ve declared this job an ‘environment’ and marked it using staging which maps to the Environment name we set up on the repo settings.
In the publish phase I specified the slot-name value mapping to the Azure App Service slot name we created on our resource in the portal.
Specify getting the AZURE_PUBLISH_PROFILE secret from the repo

You’ll also notice the ‘url’ setting on the environment. This is a cool little delighter that you should use. One of the outputs of the Azure web app deploy action is the URL to where it was deployed. I can extract that from the step and put it in this variable. GitHub Actions summary will now show this final URL in the visual map of the workflow. It is a small delighter, but you’ll see useful a bit later. Notice I don’t put any approver information in here. By declaring this in the ‘staging’ environment it will follow the protection rules we previously set up. So in fact, this job won’t run unless (1) build completes successfully and (2) the protection rules for the environment are stratified.

Deploy to production

Similarly to staging we have a final step to deploy to production. Here’s the definition snippet:

  deploy:
    needs: staging
    environment:
      name: production
      url: ${{ steps.deploy_production.outputs.webapp-url }}
    name: Deploy to production
    runs-on: ubuntu-latest
    steps:
    # Download artifacts
    - name: Download artifacts
      uses: actions/download-artifact@v2
      with:
        name: webapp

    # Deploy to App Service Linux
    - name: Deploy to Azure WebApp
      id: deploy_production
      uses: azure/webapps-deploy@v2
      with:
        app-name: ${{ env.AZURE_WEBAPP_NAME }}
        publish-profile: ${{ secrets.AZURE_PUBLISH_PROFILE }}

This is almost identical to staging except we changed:

Needs ‘staging’ to complete before this runs
Changed the environment to production to follow those protection rules
Removed the slot-name for deployment (default is production)
Changed the URL output value to the value from this job

Notice that we have the same AZURE_PUBLISH_PROFILE secret used here. Because we are declaring environments we will get the environment-specific secret in these job scopes. Helpful to have a common name and just map to different environments rather than many little ones – at least my opinion it does.

That’s it, we now have our full workflow to build –> deploy to staging with approval –> deploy to production with approval. Let’s see it in action!

Trigger the workflow

Once we have this workflow in fact we can commit/push this workflow file and it should trigger a run itself. Otherwise you can do a different code change/commit/push to trigger as well. We get a few things here when the run happens.

First we get a nicer visualization of the summary of the job:

When the protection rules are hit, a few things happen. Namely the run stops and waits, but the reviewers are notified. The notification happens in standard GitHub notification means. I have email notifications and so I got an email like this:

I can then click through and approve the workflow step and add comments:

Once that step is approved, the job runs. On the environment job it provides a nice little progress indicator of the steps:

Remember that URL setting we had? Once that job finished, you’ll see it surface in that nice summary view to quickly click through and test your staging environment:

Once we are satisfied with the staging environment we can then approve the next workflow and the same steps happen and we are deployed to production!

And we’re done!

Summary

The concept of approvals in Actions workflows has been a top request I’ve heard and I’m glad it is finally there! I’m in the process of adding it as an extra protection to all my public repo projects, whether it be for a web app deployment or a NuGet package publish, it is a helpful protection to put in place in your Actions. It’s rather simple to set up and if you have a relatively simple workflow it is equally simple to config and modify already to incorporate. More complex workflows might require a bit more thought but still simple to augment. I’ve posted my full sample here and the workflow file in the repo timheuer/actions-approval-sample where you can see the full workflow file here. This was fun to walk through and I hope this write-up helps you get started as well!

Using GitHub Actions for Bulk Resolving

2020-12-16T06:27:38Z

Today I was working on one of our internal GitHub repositories that apparently used to be used for our tooling issue tracking. I have no idea the history but a quick look at the 68 issues with the latest dating back to 2017 told me that yeah, nobody is looking at these anymore. After a quick email ack from my dev lead that I could bulk clear these out I immediately went to the repo issues list, and was about to do this:

Then I realized that all that was going to do was close them without any reasoning at all. I know that closing sends a notification to people on the issue and that wasn’t the right thing to do. I quickly looked around, did some googling and didn’t find anything in the GitHub docs that would allow me to “bulk resolve and add a message” outside of adding a commit and a bunch of “close #XXX” statements. That was unrealistic. I threw it out on Twitter in hopes maybe someone had a tool already. The other debate in my head was writing some code to iterate through them and close with a message. This felt heavy for my needs, I’d need to get tokens, blah blah. I’m lazy.

Then I thought to myself, Self, I’m pretty sure you should be able to use the ‘labeled’ trigger in GitHub Actions to automate this! Thinking this way made me think that I could use a trigger to still bulk close them but the action would be able to add a message to each one. Again, a quick thinking here led me to be writing more code than I thought…but I was on the right track. Some more searching for different terms (adding actions) and I discovered the action actions/stale to the rescue! This is a workflow designed to run on a schedule, look at ‘stale’ (to be defined by you) and label them and/or close them after certain intervals. The design looks to be something like “run every day and look for things that are X days old, label them stale, then warn that if action isn’t taken in Y days that they would be closed” – perfect for my need except I wanted to close NOW! No problem. Looking at the sample it used a schedule trigger and a CRON format for the schedule. Off to crontab.guru to help me figure out the thing I can never remember. What’s worse, regex or cron? Who knows?

And then it dawned on me! My favorite GitHub Actions tip is to add workflow_dispatch as one of the triggers to workflows. This allows you to manually trigger a workflow from your repo:

I use this ALL the time to make sure I can not have to fake a commit or something on certain projects. This was the perfect thing I needed. The combination of workflow_dispatch and this stale action would enable me to complete this quickly. I added the following workflow to our repo:

name: "Close stale issues"
on:
  workflow_dispatch:
    branches:
    - master
    
jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/stale@v3
      with:
        repo-token: ${{ secrets.GITHUB_TOKEN }}
        days-before-stale: 30
        days-before-close: 0
        stale-issue-message: 'This issue is being closed as stale'
        close-issue-message: 'This repo has been made internal and no longer tracking product issues. Closing all open stale issues.'

I just had to set a few parameters for a stale message (required) and I set the warning day basically to 0 so it would happen NOW. Then I trigger the workflow manually. Boom! The workflow ran and 2 minutes later all 68 issues were marked closed with a message that serves as the reason and the user won’t be too alarmed for some random bulk closure.

I’m glad I remembered that GitHub Actions aren’t just for CI/CD uses and can be used to quickly automate much more. In fact I’m writing this blog post maybe to help others, but certainly to serve as a bookmark to myself when I forget about this again.

Hope this helps!

Building a Code Analyzer for .NET

2020-12-12T06:33:15Z

What the heck is a code analyzer? Well if you are a Visual Studio user you probably have seen the lightbulbs and wrenches from time to time. Put it simply in my own terms, code analyzers keep an eye on your code and find errors, suggest different ways of doing things, help you know what you aren’t using, etc. Usually coupled with a code fix, an analyzer alerts you to an opportunity and a code fix can be applied to remedy that opportunity. Here’s an example:

These are helpful in your coding workflow (or intended to be!) to be more productive, learn some things along the way, or enforce certain development approaches. This is an area of Visual Studio and .NET that part of my team works on and I wanted to learn more than beyond what they are generally. Admittedly despite being on the team I haven’t had the first-hand experience of creating a code analyzer before so I thought, why not give it a try. I fired up Visual Studio and got started without any help from the team (I’ll note in one step where I was totally stumped and needed a teammates help later). I figured I’d write my experience in that it helps anyone or just serves as a bookmark for me for later when I totally forget all this stuff and have to do it again. I know I’ve made some mistakes and I don’t think it’s fully complete, but it is ‘good enough’ so I’ll carry you on the journey here with me!

Defining the analyzer

First off we have to decide what we want to do. There are a lot of analyzers already in the platform and other places, so you may not need one custom. For me I had a specific scenario come up at work where I thought hmm, I wonder if I could build this into the dev workflow and that’s what I’m going to do. The scenario is that we want to make sure that our products don’t contain terms that have been deemed inappropriate for various reasons. These could be overtly recognized profanity, accessible terms, diversity-related, cultural considerations, etc. Either way we are starting from a place that someone has defined a list of these per policy. So here is my requirements:

Provide an analyzer that starts from a specific set of known ‘database’ of terms in a structured format
Warn/error on code symbols and comments in the code
One analyzer code base that can provide different results for different severities
Provide a code fix that removes the word and fits within the other VS refactor/renaming mechnisms
Have a predictable build that produces the bits for anyone to easily consume

Pretty simple I thought, so let’s get started!

Getting started with Code Analyzer development

I did what any person would do and searched. I ended up on a blog post from a teammate of mine who is the PM in this area, Mika titled “How to write a Roslyn Analyzer” – sounds like exactly what I was looking for! Yay team! Mika’s post help me understand the basics and get the tools squared away. I knew that I had the VS Extensibility SDK workload installed already but wasn’t seeing the templates, so the post helped me realize that the Roslyn SDK is optional and I needed to go back and install that. Once I did, I was able to start with File…New Project and search for analyzer and choose the C# template:

This gave me a great starting point with 5 projects:

The analyzer library project
The code fix library project
A NuGet package project
A unit test project
A Visual Studio extension project (VSIX)

Visual Studio opened up the two key code files I’d be working with: the analyzer and code fix provider. These will be the two things I focus on in this post. First I recommend going to each of the projects and updating any/all NuGet Packages that have an offered update.

Analyzer library

Let’s look at the key aspects of the analyzer class we want to implement. Here is the full template initially provided

public class SimpleAnalyzerAnalyzer : DiagnosticAnalyzer
{
    public const string DiagnosticId = "SimpleAnalyzer";
    private static readonly LocalizableString Title = new LocalizableResourceString(nameof(Resources.AnalyzerTitle), Resources.ResourceManager, typeof(Resources));
    private static readonly LocalizableString MessageFormat = new LocalizableResourceString(nameof(Resources.AnalyzerMessageFormat), Resources.ResourceManager, typeof(Resources));
    private static readonly LocalizableString Description = new LocalizableResourceString(nameof(Resources.AnalyzerDescription), Resources.ResourceManager, typeof(Resources));
    private const string Category = "Naming";

    private static readonly DiagnosticDescriptor Rule = new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, Category, DiagnosticSeverity.Warning, isEnabledByDefault: true, description: Description);

    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get { return ImmutableArray.Create(Rule); } }

    public override void Initialize(AnalysisContext context)
    {
        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
        context.EnableConcurrentExecution();

        context.RegisterSymbolAction(AnalyzeSymbol, SymbolKind.NamedType);
    }

    private static void AnalyzeSymbol(SymbolAnalysisContext context)
    {
        var namedTypeSymbol = (INamedTypeSymbol)context.Symbol;

        // Find just those named type symbols with names containing lowercase letters.
        if (namedTypeSymbol.Name.ToCharArray().Any(char.IsLower))
        {
            // For all such symbols, produce a diagnostic.
            var diagnostic = Diagnostic.Create(Rule, namedTypeSymbol.Locations[0], namedTypeSymbol.Name);

            context.ReportDiagnostic(diagnostic);
        }
    }
}

A few key things to note here. The DiagnosticId is what is reported to the errors and output. You’ve probable seen a few of these that are like “CSC001” or stuff like that. This is basically your identifier. The other key area is the Rule here. Each analyzer basically creates a DiagnosticDescriptor that it will produce and report to the diagnostic engine. As you can see here and the lines below it you define it with a certain set of values and then indicate to the analyzer what SupportedDiagnostics this analyzer supports. By the nature of this combination you can ascertain that you can have multiple rules each with some unique characteristics.

Custom rules

Remember we said we wanted different severities and that is one of the differences in the descriptor so we’ll need to change that. I wanted basically 3 types that would have different diagnostic IDs and severities. I’ve modified my code as follows (and removing the static DiagnosticId):

private const string HtmlHelpUri = "https://github.com/timheuer/SimpleAnalyzer";

private static readonly DiagnosticDescriptor WarningRule = new DiagnosticDescriptor("TERM001", Title, MessageFormat, Category, DiagnosticSeverity.Warning, isEnabledByDefault: true, description: Description, helpLinkUri: HtmlHelpUri);
private static readonly DiagnosticDescriptor ErrorRule = new DiagnosticDescriptor("TERM002", Title, MessageFormat, Category, DiagnosticSeverity.Error, isEnabledByDefault: true, description: Description, helpLinkUri: HtmlHelpUri);
private static readonly DiagnosticDescriptor InfoRule = new DiagnosticDescriptor("TERM003", Title, MessageFormat, Category, DiagnosticSeverity.Info, isEnabledByDefault: true, description: Description, helpLinkUri: HtmlHelpUri);

public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get { return ImmutableArray.Create(WarningRule, ErrorRule, InfoRule); } }

I’ve created 3 specific DiagnosticDescriptors and ‘registered’ them as supported for my analyzer. I also added the help link which will show up in the UI in Visual Studio and if you don’t supply one you’ll get a URL that won’t be terribly helpful to your consumers. Notice each rule has a unique diagnostic ID and severity. Now we’ve got these sorted it’s time to move on to some of our logic.

Initialize and register

We have to decide when we want the analyzer to run and what it is analyzing. I learned that once you have the Roslyn SDK installed you have available to you this awesome new tool called the Syntax Visualizer (View…Other Windows…Syntax Visualizer). It let’s you see the view that Roslyn sees or what some of the old schoolers might consider the CodeDOM.

You can see here that with it on and you click anywhere in your code the tree updates and tells you what you are looking at. In this case my cursor was on Initialize() and I can see this is considered a MethodDeclarationSyntax type and kind. I can navigate the tree on the left and it helps me discover what other code symbols I may be looking for to consider what I need my analyzer to care about. This was very helpful to understand the code tree that Roslyn understands. From this I was able to determine what I needed to care about. Now I needed to start putting things together.

The first part I wanted to do is to register the compilation start action (remember I have intentions of loading the data from somewhere so I want this available sooner). Within that I then have context to the analyzer and can ‘register’ actions that I want to participate in. For this sample purposes I’m going to use RegisterSymbolAction because I just want specific symbols (as opposed to comments or full body method declarations). I have to specify a callback to use when the symbol is analyzed and what symbols I care about. In simplest form here is what the contents of my Initialize() method now looks like:

public override void Initialize(AnalysisContext context)
{
    context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
    context.EnableConcurrentExecution();

    context.RegisterCompilationStartAction((ctx) =>
    {
        // TODO: load the terms dictionary

        ctx.RegisterSymbolAction((symbolContext) =>
        {
            // do the work
        }, SymbolKind.NamedType, SymbolKind.Method, SymbolKind.Property, SymbolKind.Field,
                SymbolKind.Event, SymbolKind.Namespace, SymbolKind.Parameter);
    });
}

You can see that I’ve called RegisterCompilationStartAction from the full AnalysisContext and then called RegisterSymbolAction from within that, providing a set of specific symbols I care about.

NOTE: Not all symbols are available to analyzers. I found that SymbolKind.Local is one that is not…and there was an analyzer warning that told me so!

Note that since I’m using a lambda approach here I removed the template code AnalyzeSymbol function from the class. Okay, let’s move on to actually looking at the next step and load our dictionary.

Seeding the analyzer with data

I mentioned that we’ll have a dictionary of terms already. This is a JSON file with a specific format that looks like this:

[
  {
    "TermID": "1",
    "Severity": "1",
    "Term": "verybad",
    "TermClass": "Profanity",
    "Context": "When used pejoratively",
    "ActionRecommendation": "Remove",
    "Why": "No profanity is tolerated in code"
  }
]

So the first thing I want to do is create a class that makes my life easier to work with this so I created Term.cs in my analyzer project. The class basically is there to deserialize the file into strong types and looks like this:

using System.Text.Json.Serialization;

namespace SimpleAnalyzer
{
    class Term
    {
        [JsonPropertyName("TermID")]
        public string Id { get; set; }

        [JsonPropertyName("Term")]
        public string Name { get; set; }

        [JsonPropertyName("Severity")]
        public string Severity { get; set; }

        [JsonPropertyName("TermClass")]
        public string Class { get; set; }

        [JsonPropertyName("Context")]
        public string Context { get; set; }

        [JsonPropertyName("ActionRecommendation")]
        public string Recommendation { get; set; }

        [JsonPropertyName("Why")]
        public string Why { get; set; }
    }
}

So you’ll notice that I’m using JSON and System.Text.Json so I’ve had to add that to my analyzer project. More on the mechanics of that much later. I wanted to use this to make my life easier working with the terms database I needed to.

NOTE: Using 3rd party libraries (in this case System.Text.Json is considered one to the analyzer) requires more work and there could be issues depending on what you are doing. Remember that analyzers run in the context of Visual Studio (or other tools) and there may be conflicts with other libraries. It’s nuanced, so tred lightly.

Now that we have our class, let’s go back and load the dictionary file into our analyzer.

NOTE: Typically Analyzers and Source Generators use the concept called AdditionalFiles to load information. This relies on the consuming project to have the file though and different than my scenario. Working at the lower level in the stack with Roslyn, the compilers need to manage a bit more of the lifetime of files and such and so there is this different method of working with them. You can read more about AdditionalFiles on the Roslyn repo: Using Additional Files (dotnet/roslyn). This is generally the recommended way to work with files.

For us we are going to add the dictionary of terms *with* our analyzer so we need to do a few things. First we need to make sure the JSON file is in the analyzer and also in the package output. This requires us to mark the terms.json file in the Analyzer project as Content and to copy to output. Second in the Package project we need to add the following to the csproj file in the _AddAnalyzersToOutput target:

<TfmSpecificPackageFile Include="$(OutputPath)\terms.json" PackagePath="analyzers/dotnet/cs" />

And then in the VSIX project we need to do something similar where we specify the NuGet packages to include:

<Content Include="$(OutputPath)\terms.json">
    <IncludeInVSIX>true</IncludeInVSIX>
</Content>

With both of these in place now we can get access to our term file in our Initialize method and we’ll add a helper function to ensure we get the right location. The resulting modified Initialize portion looks like this:

context.RegisterCompilationStartAction((ctx) =>
{
    if (terms is null)
    {
        var currentDirecory = GetFolderTypeWasLoadedFrom<SimpleAnalyzerAnalyzer>();
        terms = JsonSerializer.Deserialize<List<Term>>(File.ReadAllBytes(Path.Combine(currentDirecory, "terms.json")));
    }
// other code removed for brevity in blog post
}

The helper function here is a simple one liner:

private static string GetFolderTypeWasLoadedFrom<T>() => new FileInfo(new Uri(typeof(T).Assembly.CodeBase).LocalPath).Directory.FullName;

This now gives us a List<Term> to work with. These lines of code required us to add some using statements in the class that luckily an analyzer/code fix helped us do! You can see how helpful analyzers/code fixes are in your everyday usage and we take for granted! Now we have our data, we have our action we registered for, let’s do some analyzing.

Analyze the code

We basically want each symbol to do a search to see if it contains a word in our dictionary and if there is a match, then register a diagnostic rule to the user. So given that we are using RegisterSymbolAction the context provides us with the Symbol and name we can examine. We will look at that against our dictionary of terms, seeing if there is a match and then create a DiagnosticDescriptor for that in line with the severity of that match. Here’s how we start:

ctx.RegisterSymbolAction((symbolContext) =>
{
    var symbol = symbolContext.Symbol;

    foreach (var term in terms)
    {
        if (ContainsUnsafeWords(symbol.Name, term.Name))
        {
            var diag = Diagnostic.Create(GetRule(term, symbol.Name), symbol.Locations[0], term.Name, symbol.Name, term.Severity, term.Class);
            symbolContext.ReportDiagnostic(diag);
            break;
        }
    }
}, SymbolKind.NamedType, SymbolKind.Method, SymbolKind.Property, SymbolKind.Field,
    SymbolKind.Event, SymbolKind.Namespace, SymbolKind.Parameter);

In this we are looking in our terms dictionary and doing a comparison. We created a simple function for the comparison that looks like this:

private bool ContainsUnsafeWords(string symbol, string term)
{
    return term.Length < 4 ?
        symbol.Equals(term, StringComparison.InvariantCultureIgnoreCase) :
        symbol.IndexOf(term, StringComparison.InvariantCultureIgnoreCase) >= 0;
}

And then we have a function called GetRule that ensures we have the right DiagnosticDescriptor for this violation (based on severity). That function looks like this:

private DiagnosticDescriptor GetRule(Term term, string identifier)
{
    var warningLevel = DiagnosticSeverity.Info;
    var diagId = "TERM001";
    var description = $"Recommendation: {term.Recommendation}{System.Environment.NewLine}Context: {term.Context}{System.Environment.NewLine}Reason: {term.Why}{System.Environment.NewLine}Term ID: {term.Id}";
    switch (term.Severity)
    {
        case "1":
        case "2":
            warningLevel = DiagnosticSeverity.Error;
            diagId = "TERM002";
            break;
        case "3":
            warningLevel = DiagnosticSeverity.Warning;
            break;
        default:
            warningLevel = DiagnosticSeverity.Info;
            diagId = "TERM003";
            break;
    }

    return new DiagnosticDescriptor(diagId, Title, MessageFormat, term.Class, warningLevel, isEnabledByDefault: true, description: description, helpLinkUri: HtmlHelpUri, term.Name);
}

In this GetRule function you’ll notice a few things. First, we are doing this because we want to set the diagnostic ID and the severity differently based on the term dictionary data. Remember earlier we created different rule definitions (DiagnosticDescriptors) and we need to ensure what we return here matches one of them. This allows us to have one analyzer that tries to be a bit more dynamic. We are also passing in a final parameter (term.Name) in the ctor for the DiagnosticDescriptor. This is passed in the CustomTags parameter of the ctor. We’ll be using this later in the code fix so we used this as a means to pass some context from the analyzer to the code fix (the term to replace). The other part you’ll notice is that in the Diagnositc.Create method earlier we’re passing in some additional parameters as optional. These get passed to the MessageFormat string that you’ve defined in your analyzer. We didn’t mention it detail earlier but it comes in to play now. The template gave us a Resources.resx file with three values:

These are resources that are displayed in the outputs and Visual Studio user interface. MessageFormat is one that enables you to provide some content into the formatter and that’s what we are passing here. The result will be a more user-friendly message with the right context. Great I think we have all our analyzer stuff working, let’s move on to the code fix!

Code fix library

With just the analyzer – which we are totally okay to only have – we have warnings/squiggles that will present to the user (or log in output). We can optionally provide a code fix to remedy the situation. In our simple sample here we’re going to do that and simply suggest to remove the word. Code fixes also provide the user the means to suppress certain rules. This is why we wanted different diagnostic IDs earlier as you may want to suppress the SEV3 terms but not the others. Without that distinction/difference in DiagnosticDescriptors you cannot do that. Moving over to the SimpleAnalyzer.CodeFixes project we’ll open the code fix provider and make some changes. The default template provides a code fix to make the symbol all uppercase…we don’t want that but it provides a good framework for us to learn and make simple changes. The first thing we need to do is tell the code fix provider what diagnostic IDs are fixable by this provider. We make a change in the override provided by the template to provide our diagnostic IDs:

public sealed override ImmutableArray<string> FixableDiagnosticIds
{
    get { return ImmutableArray.Create("TERM001","TERM002","TERM003"); }
}

Now look in the template for MakeUppercaseAsync and let’s make a few changes. First rename to RemoveTermAsync. Then in the signature of that change it to include IEnumerable<string> so we can pass in those CustomTags we provided earlier from the analyzer. You’ll also need to pass in those custom tags to the call to RemoveTermAsync. Combined those look like these changes now in the template:

public sealed override async Task RegisterCodeFixesAsync(CodeFixContext context)
{
    var root = await context.Document.GetSyntaxRootAsync(context.CancellationToken).ConfigureAwait(false);

    // TODO: Replace the following code with your own analysis, generating a CodeAction for each fix to suggest
    var diagnostic = context.Diagnostics.First();
    var diagnosticSpan = diagnostic.Location.SourceSpan;

    // Find the type declaration identified by the diagnostic.
    var declaration = root.FindToken(diagnosticSpan.Start).Parent.AncestorsAndSelf().OfType<TypeDeclarationSyntax>().First();

    // Register a code action that will invoke the fix.
    context.RegisterCodeFix(
        CodeAction.Create(
            title: CodeFixResources.CodeFixTitle,
            createChangedSolution: c => RemoveTermAsync(context.Document, declaration, diagnostic.Descriptor.CustomTags, c),
            equivalenceKey: nameof(CodeFixResources.CodeFixTitle)),
        diagnostic);
}

private async Task<Solution> RemoveTermAsync(Document document, TypeDeclarationSyntax typeDecl, IEnumerable<string> tags, CancellationToken cancellationToken)
{
    // Compute new uppercase name.
    var identifierToken = typeDecl.Identifier;
    var newName = identifierToken.Text.Replace(tags.First(), string.Empty);

    // Get the symbol representing the type to be renamed.
    var semanticModel = await document.GetSemanticModelAsync(cancellationToken);
    var typeSymbol = semanticModel.GetDeclaredSymbol(typeDecl, cancellationToken);

    // Produce a new solution that has all references to that type renamed, including the declaration.
    var originalSolution = document.Project.Solution;
    var optionSet = originalSolution.Workspace.Options;
    var newSolution = await Renamer.RenameSymbolAsync(document.Project.Solution, typeSymbol, newName, optionSet, cancellationToken).ConfigureAwait(false);

    // Return the new solution with the now-uppercase type name.
    return newSolution;
}

With all these in place we now should be ready to try some things out. Let’s debug.

Debugging

Before we debug remember we are using some extra libraries? In order to make this work, your analyzer needs to ship those alongside. This isn’t easy to figure out and you need to specify this in your csproj files to add additional outputs to your Package and Vsix projects. I’m not going to emit them here, but you can look at this sample to see what I did. Without this, the analyzer won’t start. Please note if you are not using any 3rd party libraries then this isn’t required. In my case I added System.Text.Json and so this is required.

I found the easiest way to debug was to set the VSIX project as the startup and just F5 that project. This launches another instance of Visual Studio and installs your analyzer as an extension. When running analyzers as extensions these do NOT affect the build. So even though you may have analyzer errors, they don’t prevent the build from happening. Installing analyzers as NuGet packages into the project would affect the build and generate build errors during CI, for example. For now we’ll use the VSIX project to debug. When it launches create a new project or something to test with…I just use a console application. Remember when earlier I mentioned that the consumer project has to provide the terms dictionary? It’s in this project that you’ll want to drop a terms.json file into the project in the format mentioned earlier. This file also must be given the build action of “C# analyzer additional file” in the file properties. Then let’s start writing code that includes method names that violate our rules. When doing that we should now see the analyzer kick in and show the issues:

Nice! It worked. One of the nuances of the template and the code fix is that I need to register a code action for each of the type of declaration that we had previously wanted the analyzer to work against (I think…still learning). Without that the proper fix will not actually show/work if it isn’t the right type. The template defaults are for NamedType, so my sample using method name won’t work on the fix, because it’s not the right declaration (again, I think…comment if you know). I’ll have to enhance this later more, but the general workflow is working and if the type is named bad you can see the full end-to-end working:

Building it all in CI

Now let’s make sure we can have reproduceable builds of our NuGet and VSIX packages. I’m using my quick template that I created for creating a simple workflow for GitHub Actions from the CLI and modifying a bit. Because analyzers use VSIX, we need to use a Windows build agent that has Visual Studio on it and thankfully GitHub Actions provides one. Here’s my resulting final CI build definition:

name: "Build"

on:
  push:
    branches:
      - main
    paths-ignore:
      - '**/*.md'
      - '**/*.gitignore'
      - '**/*.gitattributes'
  workflow_dispatch:
    branches:
      - main
    paths-ignore:
      - '**/*.md'
      - '**/*.gitignore'
      - '**/*.gitattributes'
      
jobs:
  build:
    if: github.event_name == 'push' && contains(toJson(github.event.commits), '***NO_CI***') == false && contains(toJson(github.event.commits), '[ci skip]') == false && contains(toJson(github.event.commits), '[skip ci]') == false
    name: Build 
    runs-on: windows-latest
    env:
      DOTNET_CLI_TELEMETRY_OPTOUT: 1
      DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
      DOTNET_NOLOGO: true
      DOTNET_GENERATE_ASPNET_CERTIFICATE: false
      DOTNET_ADD_GLOBAL_TOOLS_TO_PATH: false
      DOTNET_MULTILEVEL_LOOKUP: 0
      PACKAGE_PROJECT: src\SimpleAnalyzer\SimpleAnalyzer.Package\
      VSIX_PROJECT: src\SimpleAnalyzer\SimpleAnalyzer.Vsix\

    steps:
    - uses: actions/checkout@v2
      
    - name: Setup .NET Core SDK
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 5.0.x

    - name: Setup MSBuild
      uses: microsoft/setup-msbuild@v1

    - name: Setup NuGet
      uses: NuGet/setup-nuget@v1.0.5

    - name: Add GPR Source
      run: nuget sources Add -Name "GPR" -Source ${{ secrets.GPR_URI }} -UserName ${{ secrets.GPR_USERNAME }} -Password ${{ secrets.GITHUB_TOKEN }}

    - name: Build NuGet Package
      run: |
        msbuild /restore ${{ env.PACKAGE_PROJECT }} /p:Configuration=Release /p:PackageOutputPath=${{ github.workspace }}\artifacts

    - name: Build VSIX Package
      run: |
        msbuild /restore ${{ env.VSIX_PROJECT }} /p:Configuration=Release /p:OutDir=${{ github.workspace }}\artifacts

    - name: Push to GitHub Packages
      run: nuget push ${{ github.workspace }}\artifacts\*.nupkg -Source "GPR"

    # upload artifacts
    - name: Upload artifacts
      uses: actions/upload-artifact@v2
      with:
        name: release-pacakges
        path: |
            ${{ github.workspace }}\artifacts\**\*.vsix
            ${{ github.workspace }}\artifacts\**\*.nupkg

I’ve done some extra work to publish this in the GitHub Package Repository but that’s just optional step and can be removed (ideally you’d publish this in the NuGet repository and you can learn about that by reading my blog post on that topic). I’ve not got my CI set up and every commit builds the packages that can be consumed! You might be asking what’s the difference between the NuGet and VSIX package. The simple explanation is that you’d want people using your analyzer on the NuGet package because that is per-project and carries with the project, so everyone using the project gets the benefit of the analyzer. The VSIX is per-machine and doesn’t affect builds, etc. That may ideally be your scenario but it wouldn’t be consistent with everyone consuming the project that actually wants the analyzer.

Summary and resources

For me this was a fun exercise and distraction. With some very much needed special assist from Jonathan Marolf on the team I learned a bunch and needed help on the 3rd party library thing mentioned earlier. I’ve got a few TODO items to accomplish as I didn’t fully realize my goals. The code fix isn’t working exactly how I want and would have thought, so I’m still working my way through this. This whole sample by the way is on GItHub at timheuer/SimpleAnalyzer for you to use and point out my numerous mistakes of everything analyzer and probably C# even…please do! In fact in my starting this and conversing with a few on Twitter, a group in Australia created something very similar that is already published on NuGet. Check out merill/InclusivenessAnalyzer which aims to improve inclusivity in code. The source like mine is up on GitHub and they have it published in the NuGet Gallery you can add to your project today!

There are a few resources you should look at if you want this journey yourself:

How to write a Roslyn analyzer
Learn Roslyn Now from Josh Varty (blog, videos)
Analyzer samples in the Roslyn repo
Roslyn SDK
Tutorial: Write your first analyzer

Generate a GitHub Actions workflow file from dotnet CLI

2020-11-03T18:54:33Z

I’ve become a huge fan of DevOps and spending more time ensuring my own projects have a good CI/CD automation using GitHub Actions. The team I work on in Visual Studio for .NET develops the “right click publish” feature that has become a tag line for DevOps folks (okay, maybe not in the post flattering way!). We know that a LOT of developers use the Publish workflow in Visual Studio for their .NET applications for various reasons. In reaching out to a sampling and discussing CI/CD we heard a lot of folks talking about they didn’t have the time to figure it out, it was too confusing, there was no simple way to get started, etc. In this past release we aimed to improve that experience for those users of Publish to help them very quickly get started with CI/CD for their apps deploying to Azure. Our new feature enables you to generate a GitHub Actions workflow file using the Publish wizard to walk you through it. In the end you have a good getting started workflow. I did a quick video on it to demonstrate how easy it is:

One of my favorite features we've been working on in @VisualStudio. Yes, Right Click Publish!!!! #devops #dotnet pic.twitter.com/Jy2jSWplam
— Tim Heuer (@timheuer) November 3, 2020

It really is that simple!

Making it simple from the start

I have to admit though, as much as I have been doing this the YAML still is not sticking in my memory enough to type from scratch (dang you IntelliSense for making me lazy!). There are also times where I’m not using Azure as my deployment but still want CI/CD to something like NuGet for my packages. I still want that flexibility to get started quickly and ensure as my project grows I’m not waiting to the last minute to add more to my workflow. I just saw Damian comment on this recently as well:

100% this.
Create a pipeline to deploy Hello World, then build on that. You'll only have to tweak the pipeline as you go instead of trying to figure out how to deploy this big complex thing at the end. https://t.co/DV8J1IXtQW
— Damian Brady #BLM (@damovisa) November 2, 2020

I totally agree! Recently I found myself continuing to go to older repos to copy/paste from existing workflows I had. Sure, I can do that because I’m good at copying/pasting, but it was just frustrating to switch context for even that little bit. My searching may suck but I also didn’t see a quick solution to this either (please point out in my comments below if I missed a better solution!!!). So I created a quick `dotnet new` way of doing this for my projects from the CLI.

I created a simple item template that can be called using the `dotnet new` command from the CLI. Calling this in simplest form:

dotnet new workflow

will create a .github\workflows\foo.yaml file where you call it from (where ‘foo’ is the name of your folder) with the default content of a workflow for .NET Core that restores/builds/tests your project (using a default SDK version and ‘main’ as the branch). You can customize the output a bit more with a command like:

dotnet new workflow --sdk-version 3.1.403 -n build -b your_branch_name

This will enable you to specify a specific SDK version, a specific name for the .yaml file, and the branch to monitor to trigger the workflow. An example of the output is here:

name: "Build"

on:
  push:
    branches:
      - main
    paths-ignore:
      - '**/*.md'
      - '**/*.gitignore'
      - '**/*.gitattributes'
  workflow_dispatch:
    branches:
      - main
    paths-ignore:
      - '**/*.md'
      - '**/*.gitignore'
      - '**/*.gitattributes'
      
jobs:
  build:
    if: github.event_name == 'push' && contains(toJson(github.event.commits), '***NO_CI***') == false && contains(toJson(github.event.commits), '[ci skip]') == false && contains(toJson(github.event.commits), '[skip ci]') == false
    name: Build 
    runs-on: ubuntu-latest
    env:
      DOTNET_CLI_TELEMETRY_OPTOUT: 1
      DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
      DOTNET_NOLOGO: true
      DOTNET_GENERATE_ASPNET_CERTIFICATE: false
      DOTNET_ADD_GLOBAL_TOOLS_TO_PATH: false
      DOTNET_MULTILEVEL_LOOKUP: 0

    steps:
    - uses: actions/checkout@v2
      
    - name: Setup .NET Core SDK
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.x

    - name: Restore
      run: dotnet restore

    - name: Build
      run: dotnet build --configuration Release --no-restore

    - name: Test
      run: dotnet test

You can see the areas that would be replaced by some input parameters on lines 6,13,38 here in this example (these are the defaults). This isn’t meant to be your final workflow, but as Damian suggests, this is a good practice to start immediately from your “File…New Project” aspect and build up the workflow as you go along, rather than wait until the end to cobble everything together. For me, now I just need to add my specific NuGet deployment steps when I’m ready to do so.

Installing and feature wishes

If you find this helpful feel free to install this template from NuGet using:

dotnet new --install TimHeuer.GitHubActions.Templates

You can find the package at TimHeuer.GitHubActions.Templates which also has the link to the repo if you see awesome changes or horrible bugs. This is a simple item template so there are some limitations that I wish it would do automatically. Honestly I started out making a global tool that would solve some of these but it felt a bit overkill. For example:

It adds the template from where you are executing. Actions need to be in the root of your repo, so you need to execute this in the root of your repo locally. Otherwise it is just going to add some folders in random places that won’t work.
It won’t auto-detect the SDK you are using. Not horrible, but would be nice to say “oh, you are a .NET 5 app, then this is the SDK you need”

Both of these could be solved with more access to the project system and in a global tool, but again, they are minor in my eyes. Maybe I’ll get around to solving them, but selfishly I’m good for now!

I just wanted to share this little tool that has become helpful for me, hope it helps you a bit!

Filtering a Bootstrap table in C# and Blazor

2020-10-20T00:37:04Z

I was finally getting around to updating a little internal app I had that showed some various data that some groups use to triage bugs. As you can imagine it is a classic “table of stuff” type dataset with various titles, numbers, IDs, etc. as visible columns. I had built it using Blazor server and wanted to update it a bit. In doing some of the updates I came across a preferred visual I liked for the grid view and applied the CASE methodology to implement that. Oh you don’t know what CASE methodology is? Copy Always, Steal Everything. In this case the culprit was Immo on my team. I know right? I couldn’t believe it either that he had something I wanted to take from a UI standpoint. I digress…

In the end I wanted to provide a rendered table UI quickly and provide a global filter:

Styling the table

I copied what I needed and realized I could be using the Bootstrap styles/tables in my use case. Immo was using just <divs> but I own this t-shirt, so I went with <table> and plus, I like that Bootsrap had a nice example for me. Off I went and changed my iteration loop. to a nice beautiful striped table. Here’s what it looked like in the styling initially:

<table class="table table-striped">
    <thead class="thead-light">
        <tr>
            <th scope="col">Date</th>
            <th scope="col">Temp. (C)</th>
            <th scope="col">Temp. (F)</th>
            <th scope="col">Summary</th>
        </tr>
    </thead>
    <tbody>
        @foreach (var forecast in forecasts)
        {
            <tr>
                <td>@forecast.Date.ToShortDateString()</td>
                <td>@forecast.TemperatureC</td>
                <td>@forecast.TemperatureF</td>
                <td>@forecast.Summary</td>
            </tr>
        }
    </tbody>
</table>

Adding a filter

Now I wanted to add some filtering capabilities more globally. Awesome “boostrap filtering” searching I went and landed on this simple tutorial. Wow! a few lines of JavaScript, sweet, done. Or so I thought. As someone who hasn’t done a lot of SPA web app development I was quickly hit with the reality that once you choose a SPA framework (like Angular, React, Vue, Blazor) that you are essentially buying in to the whole philosophy and that for the most part jQuery-style DOM manipulations will no longer be at your fingertips as easily. Sigh, off to some teammates I went to complain and look for their sympathy. Narrator: they had no sympathy.

After another quick chat with Immo who had implementing the same thing he smacked me around and said in the most polite German accent “Why don’t you just use C# idiot?” Okay, I added the idiot part, but I felt like he was typing it and then deleted that part before hitting send. Knowing that Blazor renders everything and then re-renders when things change I just had to implement some checking logic in the foreach loop. First I needed to add the filter input field:

<div class="form-group">
    <input class="form-control" type="text" placeholder="Filter..." 
           @bind="Filter" 
           @bind:event="oninput">
</div>
<table class="table table-striped">
...
</table>

Observe that I added an @bind and @bind:event attributes that enable me to wire these up to properties and client-side events. So I’m telling it to bind the input to my ‘Field’ property and do this on ‘oninput’ (basically when the keys are typed in the input box). Now off to implement the property. I’m doing this simply in the @code block of the page itself:

@code {
    private WeatherForecast[] forecasts;

    protected override async Task OnInitializedAsync()
    {
        forecasts = await ForecastService.GetForecastAsync(DateTime.Now);
    }

    public string Filter { get; set; }
}

And then I needed to implement the logic for filtering. I’m doing a global filter so that I can control whatever fields I want searched/filtered. I basically have the IsVisible function called each iteration and deciding if it should be rendered. For this sample I’m looking at if the summary contains the filter text or if the celsius or farenheit temperatures start with the digits being entered. I actually have access to the item model so I could even filter off of something not visible if I wanted (which would be weird for your users, so you probably shouldn’t do that). Here’s what I implemented:

public bool IsVisible(WeatherForecast forecast)
{
    if (string.IsNullOrEmpty(Filter))
        return true;

    if (forecast.Summary.Contains(Filter, StringComparison.OrdinalIgnoreCase))
        return true;

    if (forecast.TemperatureC.ToString().StartsWith(Filter) || forecast.TemperatureF.ToString().StartsWith(Filter))
        return true;

    return false;
}

Implementing the filter

Once I had the parameter, input event, and the logic, now I just needed to implement that in my loop. A simple change to the foreach loop does the trick:

<table class="table table-striped">
    <thead class="thead-light">
        <tr>
            <th scope="col">Date</th>
            <th scope="col">Temp. (C)</th>
            <th scope="col">Temp. (F)</th>
            <th scope="col">Summary</th>
        </tr>
    </thead>
    <tbody>
        @foreach (var forecast in forecasts)
        {
            if (!IsVisible(forecast))
                continue;
            <tr>
                <td>@forecast.Date.ToShortDateString()</td>
                <td>@forecast.TemperatureC</td>
                <td>@forecast.TemperatureF</td>
                <td>@forecast.Summary</td>
            </tr>
        }
    </tbody>
</table>

Now when I type it automatically filters the view based on input. Like a thing of beauty. Here it is in action:

Pretty awesome. While I’ve used the default template here to show this example, this technique can of course be applied to your logic. I’ve put this in a repo to look at more detailed (this is running .NET 5-rc2 bits) at timheuer/BlazorFilteringWithBootstrap.

More advanced filtering

This was a simple use case and worked fine for me. But there are more advanced use-cases, better user experiences to provide more logic to the filter (i.e., define your own contains versus equals, etc.) and that’s where 3rd party components come in. There are a lot that provide built-in grids that have this capability. Here are just a few:

Just to name a few popular ones. These are all great components authored by proven vendors in the .NET component space. These are way richer than simple filtering and provide a plethora of capabilities on top of grid-based rendering of large sets of data. I recommend if you have those needs you check them out.

I’m enjoying my own journey writing Blazor apps and hope you found this dumb little sample useful. If not, that’s cool. I mainly am bookmarking here for my own use later when I forget and need to search…maybe I’ll find it back on my own site.

Hope this helps!

Hosting Blazor WebAssembly in Azure Static Web Apps (Preview)

2020-05-20T21:18:57Z

At Build the Azure team launched a new service called Azure Static Web Apps in preview. This service is tailored for scenarios that really work well when you have a static web site front-end and using things like serverless APIs for your communication to services/data/etc. You should read more about it here: Azure Static Web Apps .

Awesome, so Blazor WebAssembly (Wasm) is a static site right? Can you use this new service to host your Blazor Wasm app? Let’s find out!

NOTE: This is just an experiment for me. This isn’t any official stance of what may come with the service, but only what we can do now with Blazor apps. As you see with Azure Static Web Apps there is a big end-to-end there with functions, debug experience, etc. I just wanted to see if Blazor Wasm (as a static web app) could be pushed to the service.

As of this post the service is tailored toward JavaScript app development and works seamlessly in that setup. However, with a few tweaks (for now) we can get our Blazor app working. First we’ll need to get things setup!

Setting up your repo

The fundamental aspects of the service are deployment from your source in GitHub using GitHub Actions. So first you’ll need to make sure you have a repository on GitHub.com for your repository. I’m going to continue to use my Blazor Wasm Hosting Sample repo (which has different options as well to host Wasm apps) for this example. My app is the basic Blazor Wasm template, nothing fancy at all. Okay, we’ve got the repo set up, now let’s get the service setup.

Create the Azure Static Web App resource

You’ll need an Azure account of course and if you don’t have one, you can create an Azure account for free. Go ahead and do that and then come back here to make it easier to follow along. Once you have the account you’ll log in to the Azure portal and create a new resource using the Static Web App (Preview) resource type. You’ll see a simple form to fill out a few things like your resource group and a name for your app and the region.

The last thing there is where you’ll connect to your GitHub repo and make selections for what repo to use. It will launch you to authorize Azure Static Web Apps to make changes to your repo (for workflow and adding secrets):

Once authorized then more options show for the resource creation and just choose your org/repo/branch:

Once you complete these selections, click Review+Create and the resource will create! The process will take a few minutes, but when complete you’ll have a resource with a few key bits of information:

The URL of your app is auto-generated with probably a name that will make you chuckle a bit. Hey, it’s random, don’t try to make sense of it, just let the names like “icy cliff” inspire you. Additionally you’ll see the “Workflow file” YAML file and link. If you click it (go ahead and do that) it will take us over to your repo and the GitHub Actions workflow file that was created. We’ll take a look at the details next, but for now if you navigate to the Actions tab of your repo, you’ll see a fail. This is expected for us right now in our steps…more on that later.

In addition to the Actions workflow navigate to the settings tab of your repo and choose Secrets. You’ll see a new secret (with that random name) was added to your repo.

This is the API token needed to communicate with the service.

Why can’t you see the token itself and give the secret a different name? Great question. For now just know that you can’t. Maybe this will change, but this is the secret name you’ll have to use. It’s cool though, the only place it is used is in your workflow file. Speaking of that file, let’s take a look more in detail now!

Understanding and modifying the Action

So the initial workflow file was created and added to your workflow has all the defaults. Namely we’re going to focus on the “jobs” node of the workflow, which should start about line 12. The previous portions in the workflow define the triggers which you can modify if you’d like but they are intended to be a part of your overall CI/CD flow with the static site (automatic PR closure, etc.). Let’s look at the jobs as-is:

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
    - uses: actions/checkout@v2
    - name: Build And Deploy
      id: builddeploy
      uses: Azure/static-web-apps-deploy@v0.0.1-preview
      with:
        azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_ICY_CLIFF_XXXXXXXXX }}
        repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
        action: 'upload'
        ###### Repository/Build Configurations - These values can be configured to match you app requirements. ######
        app_location: '/' # App source code path
        api_location: 'api' # Api source code path - optional
        app_artifact_location: '' # Built app content directory - optional
        ###### End of Repository/Build Configurations ######

Before we make changes, let’s just look. Oh see that parameter for api token? It’s using that secret that was added to your repo. GitHub Actions has built in a ‘secrets’ object that can reference those secrets and this is where that gets used. That is required for proper deployment. So there, that is where you can see the relationship to it being used!

This is great, but also was failing for our Blazor Wasm app. Why? Well because it’s trying to build it and doesn’t quite know how yet. That’s fine, we can help nudge it along! I’m going to make some changes here. First, change the checkout version to @v2 on Line 18. This is faster.

NOTE: I suspect this will change to be the default soon, but you can change it now to use v2

Now we need to get .NET SDK set up to build our Blazor app. So after the checkout step, let’s add another to first set up the .NET SDK we want to use. It will look like this, using the setup-dotnet action:

    - uses: actions/checkout@v2
    
    - name: Setup .NET SDK
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.201

Now that we are setup, we need to build the Blazor app. So let’s add another step that explicitly builds the app and publish to a specific output location for easy reference in a later step!

    - uses: actions/checkout@v2
    
    - name: Setup .NET SDK
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.201

    - name: Build App
      run: dotnet publish -c Release -o published

There, now we’ve got it building!

NOTE: I’m taking a bit of a shortcut in this tutorial and I’d recommend the actual best practice of Restore, Build, Test, Publish as separate steps. This allows you to more precisely see what is going on in your CI and clearly see what steps may fail, etc.

Our Blazor app is now build and prepared for static deployment in the location ‘published’ referenced in our ‘-o’ parameter during build. All the files we need start now at the root of that folder. A typical Blazor Wasm app published will have a web.config and a wwwroot at the published location.

Let’s get back to the action defaults. Head back to the YAML file and look for the ‘app_location’ parameter in the action. We now want to change that to our published folder location, but specifically the wwwroot location as the root (as for now the web.config won’t be helpful). So you’d change it to look like this (a snippet of the YAML file)

    - uses: actions/checkout@v2
    
    - name: Setup .NET SDK
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.201

    - name: Build App
      run: dotnet publish -c Release -o published

    - name: Build And Deploy
      id: builddeploy
      uses: Azure/static-web-apps-deploy@v0.0.1-preview
      with:
        azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_ICY_CLIFF_XXXXXXXXX }}
        repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
        action: 'upload'
        ###### Repository/Build Configurations - These values can be configured to match you app requirements. ######
        app_location: 'published/wwwroot' # App source code path
        api_location: '' # Api source code path - optional
        app_artifact_location: 'published/wwwroot' # Built app content directory - optional
        ###### End of Repository/Build Configurations ######

This tells the Static Web App deployment steps to push our files from here. Go ahead and commit the workflow file back to your repository and the Action will trigger and you will see it complete:

We have now successfully deployed our Blazor Wasm app to the Static Web App Preview service! Now you’ll note that there is a lot of output in the Deploy step, including warnings about build warnings. For now this is okay as we are not relying on the service to build our app (yet). You’ll also see the note about Functions not being found (reminder we changed our parameter to not have that value). Let’s talk about that.

What about the Functions?

For now the service will automatically build a JavaScript app including serverless functions built using JavaScript in this one step. If you are a .NET developer you’ll most likely be building your functions in C# along with your Blazor front-end. Right now the service doesn’t automatically allow you to specify an API location in your project for C# function classes and automatically build them. Hopefully in the future we will see that be enabled. Until then you’ll have to deploy your functions app separately. You can do it in the same workflow though if it is a part of your same repo. You’ll just leverage the other Azure Functions GitHub Action to accomplish that. Maybe I should update my sample repo to also include that?

But wait, it is broken!

Well maybe you find out that the routing of URLs may not work all the time. You’re right! You need to supply a routes.json file located in your app’s wwwroot directory to provide the global rewrite rule so that URLs will always work. The routes.json file should look like

{
  "routes": [
    {
      "route": "/*",
      "serve": "/index.html",
      "statusCode": 200
    }
  ]
}

and put in your source project’s wwwroot folder. This will be picked up by the service and interpreted so routes work!

Considerations and Summary

So you’ve now seen it’s possible, but you should also know the constraints. I’ve already noted that you’ll need to deploy your Functions app separately and you have to build your Blazor app in a pre-step (which I think is a good thing personally), so you may be wondering why might you use this service. I’ll leave that answer to you as I think there are scenarios will it will be helpful and I do believe this is just a point in time for the preview and more frameworks hopefully will be supported. I know those of us on the .NET team are working with the service to better support Blazor Wasm, for example.

Another thing that Blazor build does for you is produce pre-compressed files for Brotli and Gzip compression delivered from the server. When you host Blazor Wasm using ASP.NET Core, we deliver these files to the client automatically (via middleware). When you host using Windows App Service you can supply a web.config to have rewrite rules that will solve this for you as well (you can in Linux as well). For the preview of the Static Web App service and Blazor Wasm, you won’t automatically get this, so your app size will be the default uncompressed sizes of the assemblies and static assets.

I hope that you can give the service a try with your apps regardless of if they are Blazor or not. I just wanted to demonstrate how you would get started using the preview making it work with your Blazor Wasm app. I’ve added this specific workflow to my Blazor Wasm Deployment Samples repository where you can see other forms as well on Azure to deploy the client app.

I hope this helps see what’s possible in preview today!

Different ways to host Blazor WebAssembly (Wasm)

2020-05-12T00:01:36Z

Everyone! As a part of my responsibilities on the Visual Studio team for .NET tools I try to spend the time using our products in various different ways, learning what pitfalls customers may face and ways to solve them. I work a lot with Azure services and how to deploy apps and I’m a fan of GitHub Actions so I thought I’d share some of my latest experiments. This post will outline the various ways as of this writing you can host Blazor WebAssembly (Wasm) applications. We actually have some great documentation on this topic in the Standalone Deployment section of our docs but I wanted to take it a bit further and demonstrate the GitHub Actions deployment of those options to Azure using the Azure GitHub Actions.

Let’s get started!

If you don’t know what Blazor Wasm is then you should read a bit about What is Blazor on our docs. Blazor Wasm enables you to write your web application front-end using C# with .NET running in the browser. This is different than previous models that enabled you to write C# in the browser like Silverlight where a separate plug-in was required to enable this. With modern web standards and browser, WebAssembly has emerged as a standard to enable compilation of high-level languages for web deployment via browsers. Blazor enables you to use C# and create your web app from front-end to back-end using a single language and .NET. It’s great. When you create a Blazor Wasm project and publish the output you are essentially creating a static site with assets that can be deployed to various places as there is no hard server requirement (other than to be able to serve the content and mime types). Let’s explore these options…

ASP.NET Core-hosted

For sure the simplest way to host Blazor Wasm would be to also use ASP.NET Core web app to serve it. ASP.NET Core is cross-platform and can run pretty much anywhere. If you are likely using C# for all your development, this is likely the scenario you’d be using anyway and you can deploy your web app, which would container your Blazor Wasm assets as well to the same location (Linux, Windows, containers). When creating a Blazor Wasm site you can choose this option in Visual Studio by selecting these options:

or using the dotnet CLI using this method:

dotnet new blazorwasm --hosted -o YourProjectName

Both of these create a solution with a Blazor Wasm client app, ASP.NET Core Server app, and a shared (optional) library project for sharing code between the two (like models or things like that). This is an awesome option and your deployment method would follow the same method of deploying the ASP.NET Core app you’d already be using. I won’t focus on that here as it isn’t particularly unique. One advantage of using this method is ASP.NET Core already has middleware to properly serve the pre-compressed Brotli/gzip formats of your Blazor Wasm assets from the server, reducing the payload across the wire. You’ll see more of this in below options, but using ASP.NET Core does this automatically for you. You can deploy your app to Azure App Service or really anywhere else easily.

Benefits:

You’re deploying a ‘solution’ of your full app in one place, using the same tech to host the front/back end code
ASP.NET Core enables a set of middleware for you for Blazor routing and compression

Be Aware:

Basically billing. Know that you would most likely host in an App Service or non-serverless (consumption) model. It’s not a negative, just an awareness.

Azure Storage

If you just have the Blazor Wasm site and are calling in to a set of web APIs, serverless functions, or whatever and you just want to host the Wasm app only then using Storage is an option. I actually already wrote about this previously in this blog post Deploy a Blazor Wasm Site to Azure Storage Using GitHub Actions so I won’t repeat it here…go over there and read that detail.

Example GitHub Action Deployment to Azure Storage: azure-deploy-storage.yml

Benefits:

Consumption-based billing for storage. You aren’t paying for ‘on all the time’ compute
Blob-storage managed (many different tools to see the content)

Be Aware:

Routing: errors will need to be routed to index.html as well and even though they will be ‘successful’ routes, it will still be an HTTP 404 response code. This could be mitigated by adding Azure CDN in front of your storage and using more granular rewrite rules (but this is also an additional service)
Pre-compressed assets won’t be served as there is no middleware/server to automatically detect and serve these files. Your app will be larger than it could be if serving the compressed brotli/gzip assets.

Azure App Service (Windows)

You can directly publish your Blazor Wasm client app to Azure App Service for Windows. When you publish a Blazor Wasm app, we provide a little web.config in the published output (unless you supply your own) and this contains some rewrite information for routing to index.html. Since App Service for Windows uses IIS when you publish this output this web.config is used and will help your app routing. You can also publish from Visual Studio using this method as well:

or using GitHub Actions easily using the Azure Actions. Without the ASP.NET Core host you will want to provide IIS with better hinting on the pre-compressed files as well. This is documented in our Brotli and Gzip documentation section and a sample web.config is also provided in this sample repo. This web.config in the root of your project (not in the wwwroot) will be used during publish instead of the pre-configured one we would provide if there was none.

Example GitHub Action Deployment to Azure App Service for Windows: azure-app-svc-windows-deploy.yml

Benefits:

Easy deployment and default routing configuration provided in published output
Managed PaaS
Publish easily from Actions or Visual Studio

Be Aware:

Really just understanding your billing choices for the App Service

Azure App Service (Linux w/Containers)

If you like containers, you can put your Blazor Wasm app in a container and deploy that where supported, including Azure App Service Containers! This enables you to encapsulate a little bit more in your own container image and also control the configuration of the server a bit more. For Linux, you’d be able to specify a specific OS image you want to host your app and even supply the configuration of that server. This is nice because we need to do a bit of that for some routing rules for the Wasm app. Here is an example of a Docker file that can be used to host a Blazor Wasm app:

FROM mcr.microsoft.com/dotnet/core/sdk:3.1 AS build-env
WORKDIR /app

COPY . ./
WORKDIR /app/
RUN dotnet publish -c Release

FROM nginx:1.18.0 AS build
WORKDIR /src
RUN apt-get update && apt-get install -y git wget build-essential libssl-dev libpcre3-dev zlib1g-dev
RUN CONFARGS=$(nginx -V 2>&1 | sed -n -e 's/^.*arguments: //p') \
    git clone https://github.com/google/ngx_brotli.git && \
    cd ngx_brotli && git submodule update --init && cd .. && \
    wget -nv http://nginx.org/download/nginx-1.18.0.tar.gz -O - | tar -xz && \
    cd nginx-1.18.0 && \ 
    ./configure --with-compat $CONFARGS --add-dynamic-module=../ngx_brotli

WORKDIR nginx-1.18.0
RUN    make modules

FROM nginx:1.18.0 as final

COPY --from=build /src/nginx-1.18.0/objs/ngx_http_brotli_filter_module.so /usr/lib/nginx/modules/
COPY --from=build /src/nginx-1.18.0/objs/ngx_http_brotli_static_module.so /usr/lib/nginx/modules/

WORKDIR /var/www/web
COPY --from=build-env /app/bin/Release/netstandard2.1/publish/wwwroot .
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80 443

In this configuration we’re using an image to first build/publish our Blazor Wasm app, then using the nginx:1.18.0 image as our base and building the nginx_brotli compression modules we want to use (lines 8-19,23-24). We want to supply some configuration information to the nginx server and we supply an nginx.conf file that looks like this:

load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_brotli_static_module.so;
events { }
http {
    include mime.types;
    types {
        application/wasm wasm;
    }
    server {
        listen 80;
        index index.html;

        location / {
            root /var/www/web;
            try_files $uri $uri/ /index.html =404;
        }

        brotli_static on;
        brotli_types text/plain text/css application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript image/x-icon image/vnd.microsoft.icon image/bmp image/svg+xml application/octet-stream application/wasm;
        gzip on;
        gzip_types      text/plain application/xml application/x-msdownload application/json application/wasm application/octet-stream;
        gzip_proxied    no-cache no-store private expired auth;
        gzip_min_length 1000;
        
    }
}

Now when we deploy the Docker image is composed, provided to Azure Container Registry and then deployed to App Service for us. In the above example, the first two lines are loading the modules we build in the Docker image previously.

Example GitHub Action Deployment to Azure App Service using Linux Container: azure-app-svc-linux-container.yml

Benefits:

Containers are highly customizable, allowing you some portability and flexibility
Easy deployment from Actions and Visual Studio (you can use the same publish mechanism in VS)

Be Aware

Additional service here of using Azure Container Registry (or another registry to pull from)
Understanding your billing plan for App Service
Might need more configuration awareness to take advantage of pre-compressed assets (by default nginx requires an additional module for brotli and you’d have to rebuild it into nginx)

NOTE: The example repo has a sample configuration which adds brotli compression support for nginx

Azure App Service (Linux)

Similarly to App Service for Windows you could also just use App Service for Linux to deploy your Wasm app. However there is a big known workaround you have to achieve right now in order to enable this method. Primarily this is because there is no default configuration or ability to use the web.config like you can for Windows. Because of this if you use the Visual Studio publish mechanism it will appear as if the publish fails. Once completed and you navigate to your app you’d get a screen that looks like the default “Welcome to App Service” page if no content is there. This is a bit of a false positive :-). Your content/app DOES get published using this mechanism, but since we pus the publish folder the App Service Linux configuration doesn’t have the right rewrite defaults to navigate to index.html. Because of this I’d recommend if Linux is your desired host, that you use containers to achieve this. However you CAN do this using GitHub Actions as you manipulate the content to push.

Example GitHub Action Deployment to Azure App Service Linux: azure-app-svc-linux-deploy.yml

Benefits:

Managed PaaS

Be Aware:

Cannot publish ideally from Visual Studio
No pre-compressed assets will be served
Understand your billing plan for App Service

Summary

Just like you have options with SPA frameworks or other static sites, for a Blazor Wasm client you have similar options as well. The unique aspects of pre-compressed assets provide some additional config you should be aware of if you aren’t using ASP.NET Core hosted solutions, but with a small bit of effort you can get it working fine.

All of the samples I have listed here are provided in this repository: timheuer/blazor-deploy-samples and would love to see any issues you may find. I hope this helps summarize the documentation we have on configuring options in Azure to support Blazor Wasm. What other tips might you have?

Stay tuned for more!

Skipping CI in GitHub Actions Workflows

2020-01-29T20:28:11Z

One of the things that I like about Azure DevOps Pipelines is the ability to make minor changes to your code/branch but not have full CI builds happening. This is helpful when you are updating docs or README or things like that which don’t materially change the build output. In Pipelines you have the built-in functionality to put some comments in the commit message that trigger (or don’t trigger rather) the CI build to stop. The various ones that are supported are identified in ‘Skipping CI for individual commits’ documentation.

Today that functionality isn’t built-in to GitHub Actions, but you can add it as a base part of your workflows with the help of being able to get to the context of the commit before a workflow starts! Here is an example of my workflow where I look for it:

name: .NET Core Build and Deploy

on:
  push:
    branches:
      - master

jobs:
  build:
    if: github.event_name == 'push' && contains(toJson(github.event.commits), '***NO_CI***') == false && contains(toJson(github.event.commits), '[ci skip]') == false && contains(toJson(github.event.commits), '[skip ci]') == false
    name: Build Package 
    runs-on: ubuntu-latest

You can see at Line 10 that I’m looking at the commit message text for: ***NO_CI***, [ci skip], or [skip ci]. If any of these are present then the job there does not run. It’s as simple as that! Here is an example of my last commit where I just was updating the repo to include the build badge:

And you can see in the workflows that it was not run:

A helpful little tip to add to your workflows to give you that flexibility! Hope this helps!

Tim Heuer

Another selfish tool–Endpoint for VS Code

What problem this is trying to solve (for me)

But don’t `.http` files already do this?

What about other existing GUI tools?

What Endpoint gives me (in practice)

Summary

AI in My Developer Workflow: From Prompting to Planning

Early Exploration: Terse Prompts, Terse Results

The Shift: Planning First, Prompting Second

Agents and Longer-Lived Context

Sessions, State, and Knowing When to Start Fresh

Different Models for Different Jobs

Debug inner-loop

An Honest Take: I Still Prefer a GUI

Acknowledging the Privilege

Where I Have Landed

Adding environment vars to .NET Aspire services

Anatomy of a .NET devcontainer

Base Image

Features

Extras

Customizations

Commands

Summary

Monitor your GitHub Actions in Visual Studio

How to launch it

Categories

Options

Managing Workflows

Managing Secrets

Get Started and Log Issues

Creating a VS Code editor extension

Custom Editors and UI

Editing in the vscode-data-grid

Deleting items in the grid

Adding a new item

Using the default editor

Using the custom editor as a previewer

Check out the codez

Make your VS Code extension more helpful

The Manifest

Repository

Bugs

Q&A

Keywords

Badges

Snippets

Menus

Summary

Writing an OpenAI plugin for ChatGPT using ASP.NET Core

Working with ChatGPT plugins

Writing the API

Exposing the API to ChatGPT

Using Middleware to configure the manifest

Putting it together

Sample code

Contain your excitement for ASP.NET on Azure

Cloud native

Creating and deploying a container

Publish

Leveraging continuous integration and deployment (CI/CD)

Cool, but I have advanced needs…

Summary

GitHub Composite Actions are fast way to templatize workflows

Limited Edition Custom .NET Cycling Jersey

Forcing a failure in GitHub Actions based on a condition

Creating your condition to inspect

Evaluating your condition and failing the step manually

Summary

Adding approval workflow to your GitHub Action

Setting things up

Environments

Setting up the workflow

Build

Deploy to staging

Deploy to production

Trigger the workflow

Summary

Using GitHub Actions for Bulk Resolving