Shiki is arguably the most popular syntax highlighter out there. How can we improve its performance?

Caching Shiki for Faster Build Times

Shiki is arguably the most popular syntax highlighter out there. It uses the [TextMate grammar system](https://macromates.com/manual/en/language_grammars) with the [VS Code Oniguruma library](https://github.com/microsoft/vscode-oniguruma) to tokenize strings which then can be stylized using VS Code themes or CSS variables. Shiki is the way to go if you want your code to look exactly like that in VS Code.

> Using Shiki is practical because as your favorite languages and themes evolve, your syntax highlighting will evolve as well.

If you're here for the faster build times, go to [faster build times](#faster-build-times). If you've never heard of or used Shiki before, here's a great introduction:

## How does it work?

Although Shiki has a lot of customization options (themes, languages, and custom renderers), at its core, Shiki's [highlighter](https://github.com/shikijs/shiki/blob/main/packages/shiki/src/highlighter.ts) is incredibly easy to work with:

1. Call `getHighlighter` with the theme and languages you need to create a `highlighter` instance, and then
2. Use the `highlighter` methods, such as `codeToHtml`, to take a string of code and transform it to syntax-highlighted HTML.

Of course, there are more details, so make sure to check out [Shiki's configuration and options](https://github.com/shikijs/shiki/tree/main#configuration-and-options). However, if you want to keep things simple, here's how you'd get started:

```js
import { getHighlighter } from "shiki";

// Create a highlighter instance
const highlighter = await getHighlighter({
  theme: "nord",
  langs: ["ts"],
});

const code = `console.log("Here is your code.");`;

// Call a highlighter method to get syntax-highlighted HTML
const output = highlighter.codeToHtml(code, { lang: "ts" });
```

## What are the easiest customizations you can use?

### Using CSS variables for theming

One of the biggest things missing in Shiki is the lack of support for light/dark or dual-theming. While there are several solutions and alternatives out there, none are directly addressed by the library. If you're not restricted to using VS Code themes, you can use **CSS variables for theming**.

```js
import { getHighlighter } from "shiki";

// Create a highlighter instance
const highlighter = await getHighlighter({
  // ✅ Use CSS variables for theming
  theme: "css-variables",
  langs: ["ts"],
});
```

Then use CSS to style your code and create the theming implementation of your choice. Here's a safe starting point for this:

```css
:root {
  --shiki-color-text: #24292f;
  --shiki-color-background: #ffffff;
  --shiki-token-constant: #0550ae;
  --shiki-token-string: #24292f;
  --shiki-token-comment: #6e7781;
  --shiki-token-keyword: #cf222e;
  --shiki-token-parameter: #24292f;
  --shiki-token-function: #8250df;
  --shiki-token-string-expression: #0a3069;
  --shiki-token-punctuation: #24292f;
  --shiki-token-link: #000012;
}

:root .dark-theme {
  --shiki-color-text: #c9d1d9;
  --shiki-color-background: #0d1117;
  --shiki-token-constant: #79c0ff;
  --shiki-token-string: #a5d6ff;
  --shiki-token-comment: #8b949e;
  --shiki-token-keyword: #ff7b72;
  --shiki-token-parameter: #c9d1d9;
  --shiki-token-function: #d2a8ff;
  --shiki-token-string-expression: #a5d6ff;
  --shiki-token-punctuation: #c9d1d9;
  --shiki-token-link: #000012;
}
```

Note: If you prefer to stick with VS Code Themes you might want to check out Anthony Fu's [Shikiji](https://github.com/antfu/shikiji#lightdark-dual-themes), which is an ESM-focused rewrite of Shiki.

### Using custom renderers and CSS counters for line numbers

Custom renderers allow you to define your own custom rendering rules per each element type. The easiest way to understand how custom renderers work is by creating a renderer for line numbers. Instead of using `codeToHtml`, you can use `codeToThemedTokens` from your highlighter instance to obtain an array of tokens and then call `renderToHTML`, passing your tokens and your custom renderer.

```js
import { getHighlighter, renderToHTML } from "shiki";

// Create a highlighter instance
const highlighter = await getHighlighter({
  // ✅ Use CSS variables for theming
  theme: "css-variables",
  langs: ["ts"],
});

const code = `console.log("Here is your code.");`;

// ✅ Tokenize your code to apply your custom renderer
const tokens = highlighter.codeToThemedTokens(code, "ts");

// ✅ Use your custom renderer to get syntax-highlighted HTML
const output = renderToHTML(tokens, {
  elements: {
    line({ children, className, index }) {
      return `<span data-line=${index}
        class=${className}>${children}</span>`;
    },
  },
});
```

You can combine renderers with CSS to create any implementation you might need. Here is an example using [CSS Counters](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_counter_styles/Using_CSS_counters) (with a touch of TailwindCSS) for this purpose:

```css
.shiki code {
  @apply grid p-5 font-mono text-sm leading-normal;
}

code {
  counter-reset: line;
}

code > [data-line]::before {
  counter-increment: line;
  content: counter(line);
  @apply mr-6 inline-block w-4 text-right text-gray-500/50;
}

code[data-line-numbers-max-digits="2"] > [data-line]::before {
  @apply w-8;
}

code[data-line-numbers-max-digits="3"] > [data-line]::before {
  @apply w-12;
}
```

A font pairing that I've enjoyed recently is [Schibsted Grotesk](https://fonts.google.com/specimen/Schibsted+Grotesk) with [IBM Plex Mono](https://fonts.google.com/specimen/IBM+Plex+Mono?query=IBM+PLex+Mono). Alright, now let's get to what we're here for _How to get faster build times using Shiki?_

## Faster build times

Regardless of how you use Shiki, the more code you highlight, the more likely it is that you will run into performance issues. After testing, our team concluded that **(a) creating Highlighter instances, (b) loading languages, and (c) generating token explanations are Shiki's most resource-intensive operations**.

> You should make sure that the Highlighter instance is only created once, and that it is bootstrapped asynchronously before calling any of the exposed functions

Shiki provides you with the flexibility to create the implementations you need to meet your syntax highlighting requirements, but you should exercise caution when using this flexibility. There's no built-in caching system or checks to make sure that the Highlighter instance is only created once, so you'll need to create your own.

Creating a caching system doesn't have to be overly complicated. By leveraging [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) and abstracting the `getHighlighter` method, you can achieve this.

```ts
import shiki, { type Highlighter, type Theme, type Lang } from "shiki";

// ✅ Use Map to store Highlighter instance promises
const highlighterCache = new Map<string, Promise<Highlighter>>();

export async function getHighlighter({
  theme,
  langs,
}: {
  theme: Theme;
  langs: Lang[];
}) {
  // ✅ Generate identifiers for your instances, check and return if found
  const key = [theme, ...langs].join("-");
  const highlighter = highlighterCache.get(key);
  if (highlighter) return await highlighter;

  // ✅ If an instance hasn't been created, store it and return it
  const highlighterPromise = shiki.getHighlighter({ theme, langs });

  highlighterCache.set(key, highlighterPromise);
  return await highlighterPromise;
}
```

### A word on Shiki's explanations

Shiki's explanations are the biggest hidden bottleneck, though. Understanding Shiki's explanations is key to optimizing performance. Explanations are set to `false` if you're using `codeToHtml`, but with `codeToThemedTokens` you'll find the option: `includeExplanation`, which annotates this option and describes explanations as:

> Whether to include an explanation of each token's matching scopes and why it's given its color. It defaults to false to reduce output verbosity.

Interestingly enough, explanations are considered and included in the source code for both methods. They are exposed to the developer only with `codeToThemedTokens` and documented with a default value of `false`. However, **it turns out that the default value for this option is set to true**, so if performance is your concern and you do not need to make use of explanations, set this option to `false`.

```js
import { getHighlighter } from "@lib/shiki"; // Shiki Cache Abstraction
import { renderToHTML, type Theme, type Lang } from "shiki";

/** ✅ Config */
const theme: Theme = "css-variables";
const lang: Lang = "ts";

const highlighter = await getHighlighter({
  theme,
  langs: [lang],
});

const code = `console.log("Here is your code.");`;

// ✅ Avoid getting explanations if you do not need them
const tokens = highlighter.codeToThemedTokens(code, lang, theme, {
  includeExplanation: false,
});

const output = renderToHTML(tokens, {
  elements: {
    line({ children, className, index }) {
      return `<span data-line=${index}
        class=${className}>${children}</span>`;
    },
  },
});
```

## Final thoughts

If you're using any flavor of markdown and do not need control over Shiki, plugins like [Rehype Pretty Code](https://github.com/atomiks/rehype-pretty-code), which integrate custom renders and caching systems, are excellent choices that align with the concepts explored in this article.

This simple caching and setup solution made our build times a remarkable **80% faster**. We tried various other suggestions, but none worked as effectively as creating a caching system for Shiki Highlighter instances. By implementing these strategies, you can ensure a smoother and faster syntax highlighting experience for your projects.

Here are a couple of things to keep in mind:

- The keys used to identify instances are prone to duplicates if Highlighter instances are created using different aliases, i.e. `typescript` and `ts`. Check Shiki's [language aliases](https://github.com/shikijs/shiki/blob/main/docs/languages.md#all-languages) and make sure your team has a convention for their use.
- You might not need to build your own caching system. If you aren't using Shiki directly, chances are that this has already been addressed by the libraries you're using.
- Using Shiki in the browser might require a different approach, make sure to check [Shiki's architecture to learn more](https://github.com/shikijs/shiki/blob/main/docs/languages.md#all-languages).

Huge thanks to: [@ChcJohnie](https://github.com/ChcJohnie) and [@ericvalcik](https://github.com/ericvalcik) for these findings.

The Hidden Costs of Misusing Scheduled Jobs and Messaging Systems

It's a common scenario we've all faced: you've got a table and a scheduled job designed to process this table.

Below is a simplified example of what such a script might look like:
```sql
-- Declare a variable to store the ID of the row to be processed
DECLARE @rowID INT

-- Get the first row from the table to process
SELECT TOP 1 @rowID = ID
FROM TableToProcess
ORDER BY ID ASC

-- Check if a row was found
IF @rowID IS NOT NULL
BEGIN
    -- Perform processing on the selected row (You can put your processing logic here)
    -- For now, we'll add a comment to indicate where the processing happens

    -- Delete the processed row from the table
    DELETE FROM TableToProcess WHERE ID = @rowID
END
```

But what happens when there's no new data to process? Without any contingency, the script will repeatedly hammer your database with fruitless calls, generating redundant traffic and potentially impacting the performance of your entire system.

Now, don't get me wrong. Scheduled jobs are not the enemy. They have a critical role in certain situations, such as scheduling regular email alerts. However, as developers, we sometimes fall into the trap of over-reliance on this tool, leading to unnecessary overhead within our systems.

So, is there a better, more efficient alternative to deal with these situations? Welcome to the realm of messaging systems.

## So, What's a Messaging System?

In essence, a messaging system provides a reliable way to exchange information (in the form of messages) between applications, systems, or services. The main idea here is to enable communication between different components without them necessarily knowing about each other. 

In a messaging system, producers create messages and put them onto the system. Consumers get those messages and do something with them. These systems are crucial for enabling asynchronous processing, meaning that your components don't have to wait around for other tasks to finish. This can significantly enhance performance, scalability, and reliability.

## Message Flow vs Scheduled Task

### Advantages

1. **Real-time Processing**: Messages are processed as they arrive, leading to faster responses.
2. **Decoupling of Processes**: Allows systems to be developed, upgraded, and scaled independently.
3. **Improved Scalability**: Messaging systems can more easily scale to handle larger loads.
4. **Reduced Database Load**: By processing data as it comes in, constant database querying can be reduced.
5. **Resilience**: Messaging systems can handle failures without losing data.

### Disadvantages

1. **Complexity**: Messaging systems come with their own complexities that require more advanced understanding and maintenance.
2. **Handling Failures**: Although resilient, handling failures, "poison messages," and ensuring message ordering can be challenging.
3. **Infrastructure Requirements**: Establishing and maintaining a robust messaging system might require significant resources and expertise.


## Popular Messaging System Implementations

Now that you've got a taste of a messaging system let's dive into some popular implementations: Azure Service Bus, Kafka, Azure Queue System, and RabbitMQ. 

### Azure Service Bus

Azure Service Bus is a fully managed service from Microsoft Azure that supports queue and topic, messaging models. It's robust, provides guaranteed message delivery, and maintains the order of messages. Here's an example of sending a message with Azure Service Bus in C#:

```csharp
ServiceBusClient client = new ServiceBusClient("<connection_string>");
ServiceBusSender sender = client.CreateSender("<queue_name>");

ServiceBusMessage message = new ServiceBusMessage("Hello, World!");

await sender.SendMessageAsync(message);

Console.WriteLine($"Sent a single message to the queue: {sender.EntityPath}");
```

And here is how would consumer look like 
```csharp
string connectionString = "<connection_string>";
string queueName = "<queue_name>";

await using (ServiceBusClient client = new ServiceBusClient(connectionString))
{
    ServiceBusProcessor processor = client.CreateProcessor(queueName, new ServiceBusProcessorOptions());

    processor.ProcessMessageAsync += async args =>
    {
        string body = args.Message.Body.ToString();
        Console.WriteLine($"Received message: {body}");
        await args.CompleteMessageAsync(args.Message);
    };

    processor.ProcessErrorAsync += args =>
    {
        Console.WriteLine($"Error occurred: {args.Exception}");
        return Task.CompletedTask;
    };

    await processor.StartProcessingAsync();

    Console.WriteLine("Press any key to stop receiving messages...");
    Console.ReadKey();

    await processor.StopProcessingAsync();
```

And if you start using Azure function the implementation if even shorter and simple!

```csharp
[FunctionName("ServiceBusConsumer")]
public static async Task Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_string>")] string messageBody,
    ILogger log)
{
    log.LogInformation($"Received message: {messageBody}");

    // Process the message (you can replace this with your custom logic)

    // Note: Unlike the previous examples, the message is automatically marked as completed (removed from the queue) by the Function after successful processing.
}
```

### Azure Queue System

Azure Queue System is another Microsoft offering specifically for storing large numbers of messages that may be accessed from anywhere via authenticated calls. It's simpler than Azure Service Bus and perfect for light workloads. An example of sending a message with Azure Queue in C# looks like this:

```csharp
QueueClient queueClient = new QueueClient("<connection_string>", "<queue_name>");
string message = "Hello, World!";
await queueClient.SendMessageAsync(message);
```

### Kafka

Apache Kafka, an open-source system, is built to handle real-time data feeds with high throughput and low-latency. Kafka operates in a distributed manner and can handle massive amounts of data. Here's a simple example of producing a message with Kafka using Java:

```java
Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("key.serializer", "org.apache.kafka.common.serialization.StringSerializer");
props.put("value.serializer", "org.apache.kafka.common.serialization.StringSerializer");

Producer<String, String> producer = new KafkaProducer<>(props);
ProducerRecord<String, String> record = new ProducerRecord<>("test", "Hello, World!");

producer.send(record);
producer.close();
```



### RabbitMQ

RabbitMQ is another open-source messaging system known for its robustness. It supports multiple messaging protocols, message queuing, delivery acknowledgment, flexible queue routing, and more. Here's a Python example of sending a message with RabbitMQ:

```python
import pika

connection = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
channel = connection.channel()

channel.queue_declare(queue='hello')

channel.basic_publish(exchange='', routing_key='hello', body='Hello, World!')

print(" [x] Sent 'Hello, World!'")
connection.close()
```

There you have it. Keep your system from getting bogged down by an overload of scheduled tasks. Give messaging systems a try and watch your application's performance and scalability reach new heights. Whether you go for a fully managed service like Azure Service Bus or Azure Queue System or an open-source option like Kafka or RabbitMQ, you'll reap the benefits of reliable, scalable, and high-performance messaging.

Did you pull a new assignment to sprinkle SAML2 magic on your .NET WebAPI using JWT with a free library? Well, your search ends here, fellow coder! By the end of this guide, you'll be equipped with a production-ready solution and glean insights into how to extend it and construct a truly enterprise-grade authentication system.

A Breezy Guide to Implementing SAML2 Authentication with JWT in .NET WebAPI using Sustainsys

Did you pull a new assignment to sprinkle SAML2 magic on your .NET WebAPI using JWT with a free library? Well, your search ends here, fellow coder! By the end of this guide, you'll be equipped with a production-ready solution and glean insights into how to extend it and construct a truly enterprise-grade authentication system.

My inspiration for this guide draws heavily from [this stackoverflow thread](https://stackoverflow.com/questions/55025336/sustainsys-saml2-sample-for-asp-net-core-webapi-without-identity) that offers a great [example](https://github.com/hmacat/Saml2WebAPIAndAngularSpaExample).

## Gearing Up: 
### Prerequisites
Before we delve into the thick of things, it would be beneficial to have:
- A basic understanding of .NET Core and C# programming. (This [article](https://jasonwatmore.com/net-7-csharp-jwt-authentication-tutorial-without-aspnet-core-identity) by Jason Watmore is a gem!)
- Some degree of familiarity with SAML2.

But fret not. Armed with the examples provided here, you'll manage to put together a working solution. 

### Visualizing the Flow
Before we embark, let's visualize how our app's authentication flow transforms with and without SAML.

Here is really simplified sequence diagram of how basic authentication looks like:
[![SAML2 Without](https://images.prismic.io/webscopeio/7719173d-8e7f-46e6-97eb-688b931e67bb_saml2-without.png)](https://images.prismic.io/webscopeio/7719173d-8e7f-46e6-97eb-688b931e67bb_saml2-without.png)

And now with SAML2:
[![SAML2](https://images.prismic.io/webscopeio/0d047a8b-f268-4ee9-8492-49c56b243bed_saml2-with.png)](https://images.prismic.io/webscopeio/0d047a8b-f268-4ee9-8492-49c56b243bed_saml2-with.png)


## Step 1: Loading Up the Necessary Packages
First off, we need to install the necessary NuGet packages for Sustainsys, JWT, and other supporting libraries. Head to the Package Manager Console and run these commands:

```
Install-Package Sustainsys.Saml2.AspNetCore2
Install-Package Microsoft.AspNetCore.Authentication.JwtBearer
Install-Package System.IdentityModel.Tokens.Jwt
``` 

## Step 1.1: Certificates 101
SAML authentication protocol mandates certificate management, primarily used for signing and encrypting SAML assertions. Here's a brief rundown on how to handle these certificates.

For our demo, we'll use the certificate from https://stubidp.sustainsys.com/Certificate

Here's how you'd use a .pfx file:
```csharp
public static X509Certificate2 GetCertificate()
{
    X509Certificate2 certificate = new X509Certificate2(@"path/to/your/certificate.pfx", certificatePassword);
}
```


## Step 2: Configuring SAML2 & JWT Authentication
Fantastic! Now, we'll couple SAML2 authentication with Sustainsys and set up JWT authentication in our .NET WebAPI application. Open your **Startup.cs** file (or **Program.cs**, based on your configs) and add these configurations:


```csharp
JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
services
    .AddAuthentication(options =>
    {
        options.DefaultScheme = "AppScheme";
        options.DefaultSignInScheme = "AppExternalScheme"; // If you didn't have add default scheme
        options.DefaultSignOutScheme = "AppExternalScheme"; // If you didn't have add default scheme
    })
    .AddCookie("AppExternalScheme") // If you didn't have add this
    .AddJwtBearer("AppScheme", options => ...);
```


```csharp
services
    .AddAuthentication()
    // AddSaml2 must always be after AddAuthentication
    .AddSaml2(sharedOptions =>
    {
        string siteAddress = "https://your.application.example.com/" // take note!
        sharedOptions.SPOptions.EntityId = new EntityId(siteAddress); 
        sharedOptions.SPOptions.ServiceCertificates.Add(serviceCertificate);
        sharedOptions.SPOptions.AuthenticateRequestSigningBehavior = SigningBehavior.Always;
        sharedOptions.SPOptions.WantAssertionsSigned = true;

        RegisterIdentityProvider(sharedOptions, siteAddress, selectedIdentityProvider);
    });

    // Register a single identity provider
    void RegisterIdentityProvider(Saml2Options sharedOptions, string siteAddress, IdentityProviderCustomClass identityProvider)
    {
        var ip = new IdentityProvider(
            new EntityId(identityProvider.MetadataId), sharedOptions.SPOptions)
        {
            MetadataLocation = identityProvider.MetadataLocation, // example: https://stubidp.sustainsys.com/metadata
            LoadMetadata = true,
            DisableOutboundLogoutRequests = false,
            AllowUnsolicitedAuthnResponse = identityProvider.AllowUnsolicitedAuthResponse,
        };

        
        X509Certificate2 customerSsoCertificate = GetCertificate();
        ip.SigningKeys.AddConfiguredKey(customerSsoCertificate);
        
        //Finally, add identity provider to the app
        sharedOptions.IdentityProviders.Add(ip);
    }
``` 

## Step 3: Crafting New Controller Endpoints
```csharp
/// <summary>
/// Redirects the user to the SAML authentication provider (SSO)
/// </summary>
/// <param name="returnUrl">URL to which the user should return post successful authentication.</param>
[HttpGet("saml/redirect")]
public async Task<ActionResult> SamlRedirectSaml(string returnUrl)
{
    return new ChallengeResult(
        Saml2Defaults.Scheme,
        new AuthenticationProperties
        {
            RedirectUri = Url.Action(nameof(SamlLoginCallback), new { returnUrlOrError.Value.Url }),
            IsPersistent = true
        });
}

/// <summary>
/// Logs the user in (SSO).
/// </summary>
/// <param name="url">URL to which the user should return post successful authentication.</param>
[HttpGet("saml/login")]
public async Task<ActionResult> SamlLoginCallback(string url)
{
    // Use .AuthenticateAsync to verify if user authentication was successful
    AuthenticateResult authenticateResult = await HttpContext.AuthenticateAsync("AppExternalScheme");
    if (!authenticateResult.Succeeded)
    {
        return await Problem(statusCode: StatusCodes.Status401Unauthorized);
    }
    
    // Use claims to identify authenticated user 
    Collection<Claim> claimCollection = authenticateResult?.Principal?.Claims;
    if (claimCollection.Count == 0) // No claims specified
    {
        return await Problem(statusCode: StatusCodes.Status400BadRequest);
    }

    // You can use ClaimTypes instead of long string like 
    // Always refer to the identity provider documentation of your choice to match the correct claims with your app
    string? userName = claimCollection.FirstOrDefault(c => c.Name.Equals(ClaimTypes.NameIdentifier, StringComparison.OrdinalIgnoreCase)).Value;    
    Maybe<UserSecurityData> existingUser = await _userService.GetUser(userName);
    if (existingUser.HasNoValue) // User doesn't exist 
    {
        // Optional: Auto-create a user account if none exists
        Result<User> autoCreatedUser = await _userService.AutoCreateAccount(userNameOrError.Value, claimCollection);
        if (autoCreatedUser.IsFailure)
        { 
            return await Problem(statusCode: StatusCodes.Status401Unauthorized);
        }
            
        // Log in user as you normally would
        await LogInSsoUser(autoCreatedUser.Value.Id);
    }
    else
    {
        // Log in user as you normally would
        await LogInSsoUser(existingUser.Value.Id);
    }

    // Redirect user to the original address
    return Redirect(url);
}
```

## Unveiling the Hidden Treasures
This section'll explore a few more tips to enhance your solution. 

### Tap into Azure Key Vault
Did you know there's a savvy way to manage your certificates? Azure Key Vault is your secret weapon among Microsoft Azure's cloud-based services. Think of it as a secure digital chest where you can safely stash your cryptographic keys, certificates, secrets, and connection strings used by your cloud apps and services. Rather than spreading them throughout your application code or configuration files, Azure Key Vault offers centralized, safe, and scalable storage. 

To give you an idea, here's a snapshot of how you can utilize Azure Key Vault:
```csharp
public static X509Certificate2 GetCertificate()
{
    DefaultAzureCredential azureCredentials = new DefaultAzureCredential();
    CertificateClient client = new CertificateClient(new Uri($"https://{VaultName}.vault.azure.net/"), azureCredentials);

    Azure.Response<X509Certificate2> certificate = client.DownloadCertificate("CertificateName");

    return certificate.Value;
}
```

### Juggling Multiple Identity Providers
Imagine handling multiple identity providers, such as Azure AD and OKTA. No problem at all! A few modifications to our existing solution, and you're all set.

Firstly, let's revisit our existing code and integrate some additional lines. We'll begin with the registration:

```csharp
services
    .AddAuthentication()
    // AddSaml2 must always follow AddAuthentication
    .AddSaml2(sharedOptions =>
    {
        string siteAddress = "https://your.application.example.com/" // be careful here
        sharedOptions.SPOptions.EntityId = new EntityId(siteAddress); 
        sharedOptions.SPOptions.ServiceCertificates.Add(serviceCertificate);
        sharedOptions.SPOptions.AuthenticateRequestSigningBehavior = SigningBehavior.Always;
        sharedOptions.SPOptions.WantAssertionsSigned = true;

        // NEW - Here's where we register multiple identity providers
        foreach(IdentityProviderCustomClass selectedIdentityProvider in multipleIdentityProviders)
        {
            RegisterIdentityProvider(sharedOptions, siteAddress, selectedIdentityProvider);
        }

    });
``` 

Then, let's add some flavors to the `saml/redirect` endpoint by incorporating identity provider selection logic.

```csharp
[HttpGet("saml/redirect")]
public async Task<ActionResult> SamlRedirect(string returnUrl, string entity)
{
    var properties = new AuthenticationProperties
    {
        RedirectUri = Url.Action(nameof(SamlLoginCallback), new { returnUrlOrError.Value.Url }),
        IsPersistent = true
    };
    
    properties.Items.Add("idp", new EntityId(entity).Id) // NEW - This line is crucial. It explicitly defines the identity provider to use.

    return new ChallengeResult(Saml2Defaults.Scheme, properties);
}
```

### A User-Friendly Approach to Error Handling
When directing users to multiple websites, the traditional error messaging approach between the Front-End (FE) and the API can fall short. However, you can handle this user-friendly by designing a cshtml view on the API end to display error messages.

Let's look at an example. Start by creating `Error.cshtml` and `ErrorModel.cs` files:

```html
@page
@model ErrorModel
@{
    Layout = null;
}

<!DOCTYPE html>
<html>
<head>
    <title>Oops, Something Went Wrong!</title>
</head>
<body>
    <h1>Error</h1>
    <p>@Model.ErrorMessage</p>
</body>
</html>
```

```csharp
using Microsoft.AspNetCore.Mvc.RazorPages;

public class ErrorModel : PageModel
{
    public string ErrorMessage { get; set; }

    public void OnGet(string message)
    {
        ErrorMessage = message;
    }
}
```
Next, integrate this into your controller. Here's how it would look with some pre-existing code:

```csharp

[HttpGet("saml/login")]
public async Task<ActionResult> SamlLoginCallback(string url)
{
    AuthenticateResult authenticateResult = await HttpContext.AuthenticateAsync("AppExternalScheme");
    if (!authenticateResult.Succeeded)
    {
        ViewResult view = View("Error", new ErrorModel{ ErrorMessage = "Authentication failure!"});
        view.StatusCode = StatusCodes.Status401Unauthorized;

        return view;
    }
...
``` 

### Simplifying Claims Processing With a Helper Class
Claims are generally used to identify an authenticated user. You might want to consider creating a helper class to make your code easier to understand and maintain.

```csharp
 public class ClaimCollection : Collection<Claim>
{
    // Constructors...
    // ...

    public Result<UserName> GetUserName() => this.FirstOrDefault(c => c.Type.Equals(ClaimTypes.NameIdentifier, StringComparison.OrdinalIgnoreCase)));

    public Result<Email> GetEmail() => this.FirstOrDefault(c => c.Type.Equals(ClaimTypes.Email, StringComparison.OrdinalIgnoreCase));

// Add other claims as needed... 
```

### The Importance of Logging 
If you've ever been caught up in a SAML2 flow issue, you'd know how challenging it can be to identify the problem. Was it an error in the Identity Provider (IdP) configuration? Or was there a bug within your code? For this reason, it's crucial to incorporate a logging system into your application's communication with the identity provider.

The sustainsys library handles this aspect and allows for the injection of a logger. In the following example, we've used the pre-defined `AspNetCoreLoggerAdapter`, which employs the standard **Microsoft.Extensions.Logging** class.

```csharp
services
    .AddAuthentication()
    .AddSaml2(sharedOptions =>
    {
        string siteAddress = "https://your.application.example.com/" // remember this!
        sharedOptions.SPOptions.EntityId = new EntityId(siteAddress); 
        sharedOptions.SPOptions.ServiceCertificates.Add(serviceCertificate);
        sharedOptions.SPOptions.AuthenticateRequestSigningBehavior = SigningBehavior.Always;
        sharedOptions.SPOptions.WantAssertionsSigned = true;
        sharedOptions.SPOptions.Logger = new AspNetCoreLoggerAdapter(logger)  // Here's where you add the logger

... 
```


### The Charm of User-Password Authentication with SAML2
What's so special about SAML2 in .NET? With SAML2, you no longer need to implement user-password authentication separately. SAML2 seamlessly integrates into your authentication processes, allowing you to maintain your existing authentication endpoints. It handles the Single Sign-On (SSO) flow, so users can log in once and access multiple applications without having to repeatedly enter their credentials. 

## Final Thoughts
Voila! You've now become part of the elite club capable of integrating SAML2 into their .NET applications. Recognizing the potential for research headaches, I decided to put together this comprehensive guide. But don't rest on your laurels. This is just the starting point, and there's a whole universe to explore beyond. However, with this demo, you've already hit the ground running.

If you've discovered an even better solution, please share! We're all in this learning journey together. Also, a hearty shoutout to the talented team behind the Sustainsys library. Keep the coding spirit alive. Happy coding!

Have you ever found yourself in a situation where, amidst coding enthusiasm and focus, you accidentally committed an API key or secret onto GitHub? Most developers can relate to this scenario. Thankfully, ".env" files in Next.js React can save us from such blunders.

Unraveling the Magic of .env Files: Your Friendly Guide to Custom Variables in Next.js

Have you ever found yourself in a situation where, amidst coding enthusiasm and focus, you accidentally committed an API key or secret onto GitHub? Most developers can relate to this scenario. Thankfully, ".env" files in Next.js React can save us from such blunders.

## Introducing the .env File: Your Secret Keeper
Think of .env files as hidden vaults, safeguarding your top-secret info like API keys and database credentials. They protect your data from sneaky commit leaks on GitHub.

## The Rules of .env Files in Next.js

- Your .env file's hideout should be at the root of your project. Don't try to place them elsewhere; they're crafty and won't be found.
- Next.js has different costumes for the .env files based on their environment:
  - `.env`: Standard attire for all environments.
  - `.env.local`: Local disguise. Seen in all environments except 'test.'
  - `.env.development`, `.env.test`, `.env.production`: Specific attire for each environment.
  - `.env.development.local`, `.env.test.local`, `.env.production.local`: Local disguise for specific environments.
- Name your variables starting with the `REACT_APP_` prefix for the mission.

## Decoding the NEXT_PUBLIC_ prefix
When using Next.js, variables can only be accessed in the Node.js environment unless you include a prefix of either `NEXT_PUBLIC_` or `REACT_APP_`. Doing so lets you regulate which data remains on the server side and which is sent to the browser. 

Here's an illustration:
```typescript
# .env file
API_KEY_SERVER=12345678    # Only Node.js can see this
NEXT_PUBLIC_API_KEY_CLIENT=87654321  # Node.js and the browser can see this
```

## Deploying Your Secret Variables
Once you've given your variables their correct aliases, you can deploy them using the `process.env` gadget provided by Node.js. Here's an example:

You have these defined in your .env file:

```typescript
# .env file
REACT_APP_API_URL=https://api.mywebsite.com
NEXT_PUBLIC_SITE_NAME=MyCoolWebsite
```

You can then deploy these in your React components:

```javascript
// SomeReactComponent.js
import React from 'react';

const SomeReactComponent = () => {
  return (
    <div>
      <h1>Welcome to {process.env.NEXT_PUBLIC_SITE_NAME}!</h1>
      <p>We fetch data from: {process.env.REACT_APP_API_URL}</p>
    </div>
  );
};

export default SomeReactComponent;
```


## Custom TypeScript Script and .env.local
In Next.js, the `.env.local` file is meant to store environment variables that are specific to your local development environment. When you run next dev, Next.js automatically loads the environment variables from `.env.local` and makes them available in your application.

However, suppose you are trying to access these environment variables from a custom TypeScript script (outside your Next.js application). In that case, it won't be able to read them directly because the next CLI is not involved in running the custom script. The custom TypeScript script is a separate entity unaware of Next.js' environment variables.

Suppose you want your custom TypeScript script to access the environment variables from `.env.local`. In that case, you can use a package like dotenv, which loads the variables from the `.env.local` file and makes them available to your script. 

Here's how you can do it:

### Step 1: Install the dotenv package:

```bash
npm install dotenv --save
```

### Step 2: Create a dotenv configuration file in your project (e.g., dotenv-config.ts) and add the following code:

```typescript
import dotenv from 'dotenv';

// Load environment variables from .env.local file
dotenv.config({ path: '.env.local' });

// Now you can access the environment variables using process.env
const myVariable = process.env.MY_VARIABLE;
```


## Conclusion

These variables will transform into their actual values at build time. They offer flexible disguise options for different environments like development, testing, and production.

So, there you have it—an easy, secure, and flexible way to manage your secrets in Next.js React. Keep your secrets safe and happy coding.


A short guide explaining how to build a modern, cross-browser extension with web development tools like TypeScript, Tailwind, and Vite.

Building modern browser extensions with Vite and Tailwind CSS

Browser extensions have become an integral part of our lives. We use extensions to customize browsers to our liking, whether we need to add a missing functionality or tweak their looks.

Essentially, extensions are just autonomous web pages browsers render in popup windows. Using all the goodies from traditional web development like TypeScript, Tailwind, or Vite should be easy, right? Well, yes, but it might be tricky to set up, especially when building a cross-browser extension or you want to use specific features such as [HMR](https://webpack.js.org/concepts/hot-module-replacement/).

Thankfully you're just one of many struggling with this, and already existing solutions make this process much more manageable. This article will give you insight into a straightforward way of building cross-browser extensions using the latest frontend tech stack.

## Setting up the browser extension

I recommend setting up the development environment with the Vite plugin [`@samrum/vite-plugin-web-extension`](https://github.com/samrum/vite-plugin-web-extension). This plugin solves compatibility issues you would typically have to deal with yourself. To be precise, the plugin allows you to:

* Quickly bootstrap Manifest V2 and V3 browser extensions.
* Build the extension with ES modules.
* Import and use static assets as you would in a regular Vite application.
* Use HMR and Fast Refresh.

The plugin also has an `init` command, which will let you choose the Manifest version, whether or not you want to use TypeScript and the framework of your choice (React, Preact, Vue, Svelte, or no framework at all).

```
npm init @samrum/vite-plugin-web-extension@latest
```

What Manifest version you should choose depends mainly on your requirements.

Manifest V2 is tried and tested and has looser limitations than newer Manifest V3. However, the Manifest V2 is approaching its end of life, although the day when the Chrome Web Store will stop accepting Manifest V2 extensions has been postponed, and no new date has been set yet.

On the other hand, Manifest V3 has [significantly changed](https://developer.chrome.com/docs/extensions/mv3/intro/) what and how extensions can behave. The support on Chromium-based browsers is quite good already, but other browser families support Manifest V3 only partially or not at all. Firefox, for example, [publicly states](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Build_a_cross_browser_extension) the work is still in progress and subject to change.

## Adding useful dependencies

Depending on whether you are building a cross-browser extension, I recommend installing the `webextension-polyfill` package. This package will let you use the exported `browser` API, which follows the standards set by the W3 Browser Extensions group. Theoretically, this will allow you to use one API that works on Chrome, Firefox, and possibly other browser families. However, be aware it's not a 1:1 replacement for the [`chrome` API](https://developer.chrome.com/docs/extensions/reference/) as it lacks support for some APIs only available on Chrome.

```
npm i webextension-polyfill
```

If you don't need cross-browser support and have chosen to use TypeScript, I recommend installing the `@types/chrome` package, which will provide you with types for the `chrome` API.

```
npm i --save-dev @types/chrome
```

The last helpful dependency I'd like to recommend, although a bit more specialized, is the `user-agent-data-types`. It extends the `navigator` interface type with a new `navigator.userAgentData` API, which lets you query information about the user-agent (browser, platform).

```
npm i --save-dev user-agent-data-types
```

## Adding Tailwind CSS

To add Tailwind, follow their [installation guide](https://tailwindcss.com/docs/installation/using-postcss). I recommend using PostCSS as the experience felt the most seamless to me. Once you are done with the installation, you must import the stylesheets to the popup and/or options views. You can either import it in the JS main JS file or directly in HTML. For example, this is how you could import it in the popup UI's `App.tsx`.

```
import PageContent from '~/components/PageContent';
import '../../styles.css'; // 👈 A CSS file containing `@tailwind` directives

function App() {
  return (
    <main>
      <PageContent>Popup</PageContent>
    </main>
  );
}

export default App;
```

## Conclusion

The experience of developing a web application is much less cumbersome than it used to be 5 or 10 years ago. We've grown used to modern JavaScript frameworks like React or Vue, build tools like Vite, or CSS frameworks like Tailwind. Although the environment of browser extensions is somewhat special, there are existing tools that allow us to use all these tools to build modern browser extensions quickly.

A complete example built around `vite-plugin-web-extension` with React, Taiwind CSS, and other before-mentioned packages is available at [https://github.com/jozefhruska/browser-extension-example](https://github.com/jozefhruska/browser-extension-example).

A big shoutout and thanks go to Ruben Medina ([@samrum](https://github.com/samrum)) and all the contributors for making this possible!

Take a look at how git history can be improved by rebasing interactively. Join us in learning about this powerful feature and how to properly use it.

Saying goodbye to messy git history: Git Interactive Rebase

Hey, have you heard about Git interactive rebase? If you haven't, let's dive into it together. It's a true game-changer! You can use it to clean up your commit history and make it easier to understand at a glance. You also get more control over your commits, which means you can fix mistakes in your commit messages or break up big, complicated commits into smaller, bite-sized chunks.

It's like being a wizard who can shape the history however you want. Don't get me wrong, merging is cool and perfectly okay, but if you really want to take your Git history to the next level, you gotta try out Git interactive rebase.

## What is rebasing, and how does it differ from traditional merging?
So, when you merge branches in Git, you take all the changes from one branch and apply them to another. This creates a new "merge commit" that combines the changes from both branches. The downside is that your commit history can get cluttered with a bunch of these merge commits, which can make it harder to follow the evolution of your code.

Rebasing, on the other hand, lets you apply the changes from one branch onto another, as if they had been developed in sequence. This makes it look like the changes were always part of that branch from the beginning. Rebasing is great for cleaning up your commit history, because it can help you avoid creating a bunch of unnecessary merge commits. Plus, it can make it easier to keep track of the changes in your code over time.

So, while merging can be useful for bringing changes together, rebasing can help you keep your commit history cleaner and more organized. Both have their place in the Git world, but if you want to make your commits more coherent and easier to understand, rebasing might just be your new best friend!

![](https://images.prismic.io/webscopeio/fa931c64-0cc5-44ed-94f3-19b67e343c78_merge-vs-rebase.png?auto=compress,format)

## Interactive rebase: The hidden superweapon
Now that you have a concept of how traditional rebasing works, it's time to introduce a new champion into the arena: Interactive Rebase. Interactive rebasing allows selectively editing, reordering, combining, or deleting commits, providing more control over the Git history, while using the traditional rebasing under the hood to make it all possible.

The way it works is that it gets rid of the past commits and mimics them with the changes that you ordered when making new ones. And all while doing that, it rebases all the changes on the branch of your choosing. It's a perfect way to modify your own git history while staying up-to-date with the underlying base branch. Perfect!

Let's look at how a PR's commit history can look when using the merge strategy for keeping it up to date. Also, if we don't use interactive rebase, once a commit is pushed onto the remote, it's there - forever. There's no going back once it's whooshed up there.

![Example of dirty commit history](https://images.prismic.io/webscopeio/3633fcab-5d40-4094-8c26-993678c8149f_dirty-commit-history.png?auto=compress,format)

There's a lot of commits, small one-liner fixes that I've found when developing other things, and merge commits that keep the branch up to date with the base branch. Yuck. While you can see how I proceeded with my work, the history is really cluttered and if all of those commits were pasted onto the master branch without squashing the commits, I bet it would confuse the soul out of my colleagues.

## Now let's build a PR with Interactive rebasing in mind
I'll be using the Fork git client to better illustrate what I'm doing with the commits. Here's how I created the commits. This isn't something that I'd like my colleagues or clients to see! Let's interactively rebase this branch on “master”, to get the ability to edit our existing commits, while pulling the latest changes from master to stay up-to-date.

![Git Interactive Rebase process - step 1](https://images.prismic.io/webscopeio/85f06acf-24b2-4295-93dd-22810288ed6e_gir-1.png?auto=compress,format)

So, how do we make this mess look beautiful? Take a look at the dropdown menu with the green indicator and “Pick” word on it.

![Git Interactive Rebase process - step 2](https://images.prismic.io/webscopeio/db4f8362-9270-4615-bfa8-04a1ef4f1206_gir-2.png?auto=compress,format)

All of these options indicate a transformation for the commit that will happen during the rebasing process. If we were to rebase this branch straight-away, all of our commits will be “Picked”, meaning that nothing will change. Fork nicely explains how each of the actions transform the commit.

This is what we will do with this particular branch, to simplify things a little bit:

![Git Interactive Rebase process - step 3](https://images.prismic.io/webscopeio/6bd4af83-fe8b-47be-b8e0-479e040d9aba_gir-3.png?auto=compress,format)

We used the “Fixup” action to meld our commits one-by-one into the first one. When that was done, we had only one commit, but with an out-of-date (and quite ugly) commit message. So we reworded it into a nicely formatted, simple commit message. Yay! Now we can push the branch and create a PR. This is how the commit history looks now:

![Example of clean commit history](https://images.prismic.io/webscopeio/82d01984-66e9-48f9-bcac-df85dacfd0c6_clean-commit-history.png?auto=compress,format)

It feels good to have absolute control over your commits, doesn't it? If you find something to fix in retrospect, you absolutely can do it properly and add the fixing change into the former commit. 

If you want, you can have more commits in your PR's, for example one for your components, second for your type definitions, and a third for a helper function that you've just implemented. Or you can have it all at once in one bigger commit, that will be self-explanatory when merged onto the master branch. It's your call - you have all the freedom and tools to do it.

## Handle with care!
As powerful as Git interactive rebase is, it's sadly not all-mighty. There's definitely some borders to stay in when you're going ham on your git history. 

> The most important thing to remember is that you can only edit your local commits.

You can feel free to do whatever you want with commits that aren't yet on the origin, but once they're pushed onto the origin, you should take great care when manipulating them. If you really need to overwrite git history that's already pushed on the origin, you'll have to pull the branch, overwrite your commits locally with the interactive rebase, and then do a force push back onto the branch.


Solely the fact that you have to force push is an exclamation mark by itself, but let me emphasise on this once again: 

> In this case you'll be overwriting history that someone else could've based their work on.

Be sure to double check with the rest of your team that it's ok to overwrite the section you're working on, and that it won't cause any headaches for someone.

## Commit away!
Now that you know about Interactive rebasing and what it can do, there's nothing stopping you from making your git history clear and purposeful. Your mates will love to do code reviews on your branch because of the clarity, trust me on that. I was surprised how such a powerful feature is not so widely known among developers. It certainly changed my approach to commits, and I hope to have brought you fresh new information, so you can perhaps change yours.


Blog

Caching Shiki for Faster Build Times

The Hidden Costs of Misusing Scheduled Jobs and Messaging Systems

A Breezy Guide to Implementing SAML2 Authentication with JWT in .NET WebAPI using Sustainsys

Unraveling the Magic of .env Files: Your Friendly Guide to Custom Variables in Next.js

Building modern browser extensions with Vite and Tailwind CSS

Saying goodbye to messy git history: Git Interactive Rebase

Let’s stay connected