Add Static Page Generation to Blazor WebAssembly

August 26, 2026

Introduction

Blazor WebAssembly is an interesting technology for building web applications that run .NET directly in the client browser without requiring a server-side application component. It is also a Single Page Application (SPA) technology, which means that it shares many of the same characteristics as applications built with frameworks such as React, Angular, and Vue.js.

One of those characteristics is how content is rendered. The HTML returned by the server typically contains the application shell, while the actual page content is created by the application after it has started in the browser.

That can be a problem when some pages contain public content that should be discoverable by search engines, social media crawlers, AI agents, and other bots. Crawlers that only download and inspect the static HTML never see content that exists only after the SPA has rendered it. Some crawlers can execute JavaScript and render the application, but many do not.

This is where adding static page generation to Blazor WebAssembly can help.

Blazorade Static Pages adds build-time static page generation to an existing Blazor WebAssembly application. Your application remains the source of truth, and you decide which pages and which parts of those pages should also be generated as static HTML.

There are several ways to solve the discoverability problem, but I wanted an approach that would work with an ordinary Blazor WebAssembly application. I did not want to build a separate static site, duplicate routes, or make static content the foundation of the application.

In this article, I will show you how Blazorade Static Pages works, how you can mix static and interactive content, and how to start using it in your own Blazor WebAssembly application.

What About Blazorade Scraibe Then?

I previously tried to solve the same problem with Blazorade Scraibe .

The main difference is the direction. Blazorade Scraibe is content-first: you start with static content and build a Blazor WebAssembly application around it. Blazorade Static Pages is application-first: you start with an existing Blazor WebAssembly application and add static page generation only where you need it.

I believe the second approach fits Blazor WebAssembly better. These are primarily interactive applications, so it feels more natural to add discoverable static content to an existing application than to build the application around static content.

For now, I have therefore abandoned the Blazorade Scraibe approach in favour of Blazorade Static Pages.

Getting Started With Blazorade Static Pages

Getting started is quite simple. First, add the Blazorade Static Pages NuGet package to your Blazor WebAssembly application.

            
dotnet add package Blazorade.StaticPages

            

Then pick a routable page that you want to make available as static HTML and mark it with the StaticPage attribute.

            
@page "/products"

            
@attribute [StaticPage]

            

            
<StaticMetadata

            
    Title="Products"

            
    Description="Explore our products." />

            

            
<StaticContent>

            
    <h1>Products</h1>

            
    <p>Browse our product catalogue.</p>

            
</StaticContent>

            

There are three important parts here. The normal @page directive still defines the route, just like in any other Blazor application. The StaticPage attribute tells Blazorade Static Pages that this route should participate in static generation. Finally, StaticMetadata defines the metadata for the page, while StaticContent defines the content that should be included in the generated HTML.

When you build the application, Blazorade Static Pages scans the Razor source files and finds routable components marked with the StaticPage attribute. It then analyzes their static metadata and content, generates HTML files, and copies those files to the application’s build output.

Pages marked with StaticPage are also included in the generated sitemap by default. If you have a static page that you do not want to include in the sitemap, you can disable that directly on the attribute.

            
@attribute [StaticPage(IncludeInSitemap = false)]

            

The sitemap itself is generated when you have configured the public site URL for the application. I will come back to that later when we look at metadata and configuration in more detail.

Pages that are not marked with StaticPage are simply ignored by the generator and continue to behave just like any other page in your Blazor WebAssembly application. This means that you can add static generation gradually, only to the pages where you actually need it.

Static and Interactive Content

A Blazor WebAssembly page does not have to be either static or interactive. With Blazorade Static Pages, you can decide which parts of a page should be included in the generated static HTML and which parts should only exist when the Blazor application is actually running in the browser.

The StaticContent component marks content that should be included in the generated static page.

            
<StaticContent>

            
    <h1>Products</h1>

            
    <p>Browse our product catalogue.</p>

            
</StaticContent>

            

The StaticContent component itself is transparent. It does not add any extra HTML markup at runtime, and its wrapper is not emitted into the generated HTML either. Only the content inside it is included in the generated page.

Sometimes you have content inside an otherwise static section that only makes sense when the Blazor application is running. This is where InteractiveContent comes in.

            
<StaticContent>

            
    <h1>Products</h1>

            
    <p>Browse our product catalogue.</p>

            

            
    <InteractiveContent>

            
        <ProductConfigurator />

            
    </InteractiveContent>

            
</StaticContent>

            

The complete subtree inside InteractiveContent is excluded from the generated static HTML, but it renders normally when the Blazor application runs in the browser. This makes it possible to have crawler-visible content and normal Blazor interactivity on the same page without maintaining two separate implementations.

Reusable components can also participate in static generation. If a reusable component contains a StaticContent section, that section becomes the component’s static representation.

            
<StaticContent>

            
    <section class="product-summary">

            
        <h2>@Name</h2>

            
        <p>Additional details are available interactively.</p>

            
    </section>

            
</StaticContent>

            

            
<InteractiveContent>

            
    <ProductEditor />

            
</InteractiveContent>

            

When a page uses this component, Blazorade Static Pages includes only the component’s StaticContent in the generated HTML. Ordinary markup outside StaticContent is not included automatically, and a reusable component without a static representation contributes no static content.

This explicit separation is intentional. Blazorade Static Pages does not try to execute arbitrary components and hope that their output can be turned into static HTML. Instead, you decide what is safe and meaningful to publish statically, while everything that depends on runtime behavior stays in the interactive application.

How Static Generation Works

Blazorade Static Pages generates static HTML during the normal build of your Blazor WebAssembly application. The generator runs after the application has been built, scans the Razor source files, and looks for routable components marked with the StaticPage attribute.

The important thing to understand is that Blazorade Static Pages does not run your application. It does not execute components, invoke lifecycle methods, resolve services, call JavaScript, or fetch runtime data. Instead, it analyzes the source code and builds the static output from values and markup that can be determined at build time.

This makes the generation process deterministic, but there is also a more fundamental reason for this restriction: we are talking about static content. Everything that is emitted into the generated HTML needs to be static in nature too.

Reusing Compile-Time Values

You do not have to duplicate the same text in several places just because the generator works from source. Blazorade Static Pages can resolve supported compile-time string values and reuse them both in metadata and in static content.

For instance, you can define the page title and description once and reference them from both StaticMetadata and StaticContent .

            
@page "/products"

            
@attribute [StaticPage]

            

            
@code {

            
    private const string PageTitle = "Products";

            
    private const string PageDescription = "Explore our products.";

            
}

            

            
<StaticMetadata

            
    Title="@PageTitle"

            
    Description="@PageDescription" />

            

            
<StaticContent>

            
    <h1>@PageTitle</h1>

            
    <p>@PageDescription</p>

            
</StaticContent>

            

The analyzer can also resolve supported constants from matching .razor.cs code-behind files and from standard project C# files, including qualified references such as @Constants.Author .

The key point is that these values must be constants. A const value cannot change after compilation, which makes it safe to use as part of generated static HTML. A normal field, even a static field, is still mutable and therefore not truly static in this sense.

That distinction fits the purpose of the library quite well. If the generated HTML is supposed to be a deterministic static artifact, the values used to produce it must also be deterministic and unchangeable at build time.

What Cannot Be Resolved at Build Time

Because the application is not executed, runtime values cannot be used for static metadata or static content.

That includes values that depend on things such as:

• Dependency-injected services.
• Lifecycle methods.
• Property getters.
• Authentication or user-specific state.
• Browser APIs.
• External data fetched at runtime.
• Mutable fields or variables whose value can change.

Unsupported expressions cause a build error instead of silently producing incomplete static output.

If some part of a page depends on runtime behavior, that content should stay in the normal Blazor application and be placed inside InteractiveContent where appropriate.

Generated HTML

Each generated page uses the application’s existing wwwroot/index.html as its template. Blazorade Static Pages replaces the contents of the normal Blazor application root with the extracted static content, updates the page title and metadata, and keeps the rest of the application shell intact.

This means that the generated document already contains meaningful HTML when it is downloaded, but it can still start the normal Blazor WebAssembly application afterwards. The static page is the baseline, and Blazor can enhance it with interactive functionality once the application is running in the browser.

Metadata and Configuration

Static HTML is only useful if the page also contains the metadata that search engines, social media platforms, and other crawlers expect. Blazorade Static Pages therefore generates metadata alongside the static page content.

Page-specific metadata is defined with the StaticMetadata component.

            
@page "/products"

            
@attribute [StaticPage]

            

            
<StaticMetadata

            
    Title="Products"

            
    Description="Explore our products."

            
    Author="Mika Berglund"

            
    Image="images/products.jpg"

            
    Locale="en-US"

            
    Date="2026-08-26" />

            

            
<StaticContent>

            
    <h1>Products</h1>

            
    <p>Browse our product catalogue.</p>

            
</StaticContent>

            

The Title parameter is required. The other metadata values are optional, but when supplied they also need to be compile-time-resolvable values, just like the static page content.

From these values, Blazorade Static Pages generates the normal page title together with metadata such as description, author, Open Graph values, Twitter card metadata, locale, publication date, and image information.

Configuring the Public Site URL

Some metadata cannot be generated from the page itself. Canonical URLs and sitemap entries, for instance, need to know the public address where the application will eventually be hosted.

You configure that in a blazorade.config.json file next to your Blazor WebAssembly project file.

            
{

            
  "staticPages": {

            
    "siteUrl": "https://www.example.com"

            
  }

            
}

            

The configured siteUrl is combined with the normal Blazor route when generating canonical URLs.

For example:

            
https://www.example.com + /products

            
= https://www.example.com/products

            

That URL is then used for metadata such as the canonical link and og:url .

Blazorade Static Pages does not try to derive this URL from the host where the application happens to run. That would not be reliable, because the same build could be served locally, in a preview environment, or from the final production site.

Sitemap Generation

A sitemap is particularly important when you generate static pages, because it gives crawlers a clear list of the routes you want them to discover.

When staticPages.siteUrl is configured, Blazorade Static Pages generates a sitemap.xml file containing the static pages in the application. Each sitemap URL is created from the configured site URL and the normal @page route.

Static pages are included in the sitemap by default. If you have a page that should still be generated as static HTML but should not be advertised through the sitemap, you can exclude it with the StaticPage attribute.

            
@attribute [StaticPage(IncludeInSitemap = false)]

            

This lets static generation and sitemap inclusion remain separate decisions. A page can be available as static HTML without necessarily being listed in sitemap.xml .

If siteUrl is not configured, the static pages are still generated, but canonical URLs and the sitemap are omitted.

Static Web Apps Route Configuration

Blazorade Static Pages is primarily designed to be hosted with Azure Static Web Apps . That is also why the library generates a staticwebapp.config.json file as part of the static output.

The generated configuration contains an explicit rewrite for each static route, mapping the normal Blazor route to the corresponding generated HTML file. For example, a request to:

            
/products

            

can be rewritten to:

            
/products.html

            

This means that a crawler requesting /products receives the generated static HTML directly instead of having to start and render the Blazor WebAssembly application first.

The generated configuration also adds a navigation fallback to /index.html for routes that are not backed by generated static pages. This preserves the normal SPA routing behaviour for the rest of the Blazor WebAssembly application. Static assets, framework files, the sitemap, and other known files are excluded from that fallback.

In other words, Azure Static Web Apps is not just an arbitrary hosting option that happens to work with Blazorade Static Pages. It is the primary hosting model the library is designed around. Static routes are served directly as generated HTML, while the rest of the application continues to behave like a normal Blazor WebAssembly SPA.

Configuration-Specific Settings

You can also override configuration based on the active MSBuild configuration.

For example:

            
blazorade.config.json

            
blazorade.config.Debug.json

            
blazorade.config.Release.json

            
blazorade.config.Pre-Prod.json

            

Blazorade Static Pages first reads the default blazorade.config.json file and then merges values from the configuration-specific file on top of it. This means that you can use normal Visual Studio or MSBuild build configurations without introducing a separate environment mechanism just for Static Pages.

This is useful when different builds need different static generation settings while keeping the application itself unchanged.

Migrating My WordPress Blog to Blazorade Static Pages

My current blog is running on WordPress. It has worked well for me, but I am planning to migrate the site to a Blazor WebAssembly application that uses Blazorade Static Pages.

There are a couple of reasons for this. First, I will move the site into a technology stack where I feel much more at home. I spend a lot of my time working with .NET, Blazor, Azure, and related technologies, so maintaining the blog as a Blazor application feels like a natural fit.

The second reason is hosting. Blazor WebAssembly applications can be hosted as static files, which makes Azure Static Web Apps a very attractive option. Azure Static Web Apps starts with a free tier, so I expect the hosting costs for this blog to become significantly lower than they are today.

Blazorade Static Pages is an important part of that plan. The blog will still be a Blazor WebAssembly application, but the public article pages can be generated as static HTML during the build. That means search engines, crawlers, and other bots can access the article content without having to execute and render the Blazor application first.

I will write a separate article about the actual WordPress-to-Blazor migration once I have completed it. That article will cover the practical details of moving the content, routing, hosting, and everything else that turns out to be involved. When that article is available, I will update this article with a link to it.

Common Questions and Answers

Is Blazorade Static Pages a prerendering solution?

No. Blazorade Static Pages does not execute the Blazor application or render components at build time. It analyzes the Razor source files and generates static HTML from content that can be resolved directly from the source.

Does Blazorade Static Pages replace my Blazor WebAssembly application?

No. Your Blazor WebAssembly application remains the source of truth. Static Pages only adds generated HTML for the routes you explicitly mark with StaticPage .

Can a page contain both static and interactive content?

Yes. Use StaticContent for content that should be included in the generated HTML, and InteractiveContent for parts that should only be available when the Blazor application runs in the browser.

Can reusable components contribute static content?

Yes. A reusable component can expose a static representation by placing that content inside StaticContent . Only that explicitly declared static content is included in the generated page.

Can I use variables and runtime values in static content?

Only compile-time-resolvable constants and supported string expressions can be used. Runtime values, services, lifecycle state, property getters, and other mutable or dynamic values are not evaluated during static generation.

Are all Blazor pages automatically generated as static pages?

No. Only routable components marked with @attribute [StaticPage] are included in static generation. Other pages remain normal Blazor WebAssembly pages.

Does Blazorade Static Pages generate a sitemap?

Yes, when staticPages.siteUrl is configured. Static pages are included in sitemap.xml by default, but individual pages can be excluded with IncludeInSitemap = false .

Is Blazorade Static Pages designed for Azure Static Web Apps?

Primarily, yes. Blazorade Static Pages is designed with Azure Static Web Apps as its main hosting target, which is why it generates a staticwebapp.config.json file as part of the build output. That file contains route rewrites for generated static pages and a navigation fallback for the rest of the Blazor WebAssembly application.

Can I fetch data from an API during static generation?

No. The current generator does not execute application code or fetch runtime data. Content that depends on external data needs to remain runtime-only, or be represented through deterministic static content that is available at build time.

Summary

Blazorade Static Pages takes an application-first approach to static page generation. You keep building your Blazor WebAssembly application the way you normally would, and add static generation only to the pages and content that need to be discoverable outside the running application.

The generated HTML is created during the build without executing the application. Static content, metadata, sitemap entries, and Azure Static Web Apps routing configuration are all produced from information that can be resolved deterministically from the source.

For me, this approach fits Blazor WebAssembly much better than starting from static content and building an application around it. Blazor WebAssembly is primarily an application technology, and Blazorade Static Pages adds static content capabilities without changing that model.

I am also planning to use Blazorade Static Pages when I migrate this blog from WordPress to Blazor WebAssembly. I will cover that migration in a separate article once it is complete and update this article with a link to it.

Use Microsoft Foundry Models With GitHub Copilot in VS Code

August 16, 2026

GitHub Copilot is a great way to add AI-assisted development to VS Code . But what if you don’t want to decide up front which Copilot subscription gives you the models, features and capacity you need?

By using your own models deployed in Microsoft Foundry , you can use a more pay-as-you-go approach, where your costs are based on the models and resources you actually consume. You can also choose from models available in Microsoft Foundry that might not be available through your GitHub Copilot plan. In this article, I’ll show you how to connect these models to VS Code and use them in the same chat and agent workflows you are already familiar with from GitHub Copilot.

Why Use Microsoft Foundry Models?

Many developers and architects use AI as a power tool rather than as an autonomous developer. You know what you want to build and how you want to build it, but use AI to explain unfamiliar code, generate or modify code, write tests, refactor something, troubleshoot a problem, or simply get things done faster.

If most of your AI usage happens by asking GitHub Copilot to do something from the VS Code Chat interface, models deployed in Microsoft Foundry can be a very interesting alternative.

I have been using GitHub Copilot actively for around a year now, and models deployed in Microsoft Foundry with GitHub Copilot in VS Code for several months. During that time, I have tried different AI tools and integrations for VS Code, but I keep coming back to GitHub Copilot. I simply like how naturally it integrates with VS Code and fits into my everyday development workflow.

Because I have been very pleased with how well Foundry models work with this setup, I thought it was worth sharing how I use them.

By connecting VS Code to multiple Microsoft Foundry resources, you can also separate your AI usage costs between different Azure subscriptions, customers, or internal cost centers. The model usage is then billed to the corresponding Azure resources instead of everything being tied to one GitHub Copilot subscription.

I am not suggesting that models deployed in Microsoft Foundry can replace everything you get with a GitHub Copilot subscription. There are still GitHub Copilot features that require a proper Copilot plan. VS Code’s BYOK support applies to Chat and utility tasks, while features such as standard inline code completions, semantic search, and other features that rely on embeddings still depend on GitHub Copilot.

Models I Use

At the time of writing, I mainly use two models from the GPT-5.6 family. GPT-5.6 Luna has become my default workhorse, while I typically switch to GPT-5.6 Terra for trickier problems. I have been very pleased with both, and Luna in particular has turned out to be a very capable, cost-effective, and fast model.

The pricing makes Luna especially interesting for the kind of everyday AI-assisted development I describe in this article.

To put that into perspective, here are my actual usage figures after roughly two weeks of daily use. According to the monitoring information in Microsoft Foundry, I have consumed more than 80 million input tokens and over 600,000 output tokens with GPT-5.6 Luna. Looking at Cost Analysis in the Azure portal, my actual total cost for that usage has been around €5.50 .

These are not theoretical estimates or example calculations. They are the actual figures from my own Azure environment and my own daily usage.

That is a lot of AI usage for the price of a couple of cups of coffee.

Of course, your costs may be different. Pricing depends on factors such as the model, deployment type, region, how much context VS Code sends to the model, and your Azure pricing agreement. Still, my own numbers give a useful idea of why I find the pay-as-you-go approach so interesting for everyday development work.

Setting Up VS Code

Note! The examples in this article were tested with Visual Studio Code 1.133 . The functionality described here was introduced in earlier versions of VS Code, but the user interface and available configuration options may differ between versions.

The setup described in this article uses the built-in language model support in VS Code, so you don’t need to install any extensions just to connect to your Foundry models. Azure and Microsoft Foundry is one of the model providers supported directly by VS Code.

Before configuring VS Code, you need at least one suitable language model deployed in Microsoft Foundry . In my case, I have a couple of different LLMs deployed so that I can switch between them depending on what I am working on.

I will not go through the model deployment process in this article. I assume that you already know how to deploy models in Microsoft Foundry. What we need from each deployment is the endpoint, deployment name, and authentication details.

For the setup in this article, I use an API key from my Foundry project. VS Code stores the key separately from the language model configuration, so you don’t have to add the actual key to the JSON configuration.

For improved security, you can also restrict network access to your Microsoft Foundry resource. Foundry supports selected networks and private endpoints. If you restrict access this way, the computer running VS Code must naturally be able to reach the Foundry endpoint, which may mean connecting through your corporate network or VPN.

Add a Foundry Model to VS Code

The first thing you need to do is open the VS Code Command Palette by pressing Ctrl + Shift + P . Start typing Chat: Manage Language Models , and select the Chat: Manage Language Models command from the list.

image

This opens the Language Models dialog shown below. This is where you can see the models currently available in VS Code and add new models from supported providers.

image-1-1024x523

Click + Add Models , and select Azure from the list of available model providers.

image-2

For every Microsoft Foundry resource you plan to use with GitHub Copilot in VS Code, you can define a separate group for its models. If you only plan to use one Foundry resource, you can simply leave the default group name as shown below.

image-3

After defining the group name, VS Code asks for the API key that it should use to authenticate with Microsoft Foundry.

image-4

You can find the API key on the Microsoft Foundry project home page . Copy the key from there and paste it into VS Code when prompted.

After you enter the key, VS Code opens the chatLanguageModels.json configuration where you can finish configuring your models. The API key itself is stored separately and referenced from this configuration rather than being written directly into the JSON.

image-5-1024x522

The configuration allows you to define one or more LLMs for the Foundry resource you are connecting to. If some of the attributes below are not included in the empty template, you can simply add them yourself.

For each model, configure the following attributes:

• id : The deployment name you used when you deployed the model to Microsoft Foundry.
• name : The name you want to see in the model drop-down in the VS Code Chat view.
• url : The endpoint that VS Code uses to communicate with the model. I will show you below how to get the correct URL.
• toolCalling : Set this to true if the model supports tool calling. Tool calling is required if you want to use the model with agents in Chat.
• vision : Set this to true if the model supports image input.
• thinking : Set this to true if the model supports reasoning.
• maxInputTokens : The maximum number of input tokens available to the model.
• maxOutputTokens : The maximum number of output tokens the model can generate.
• editTools : Specifies which code editing tools VS Code can use with the model. I explicitly enable apply-patch , code-rewrite , multi-find-replace , and find-replace . The value for this attribute is a JSON array of strings.

The sum of maxInputTokens and maxOutputTokens must not exceed the context window supported by the model. The values therefore need to match the capabilities of the model you are configuring. The editTools property is optional. If you leave it out, VS Code can try the available editing tools and choose one automatically.

Getting the Correct Model URL

The url property is easy to get once you know where to look. Open the model deployment in Microsoft Foundry and go to the Details tab. There you will find the Endpoint URL for the model.

For instance, the endpoint for my GPT-5.6 Luna deployment looks like this:

https://<foundry-instance-name>.services.ai.azure.com/openai/v1/responses

image-6-1024x340

Copy that URL and use it as the value of the url property in your VS Code model configuration.

Complete Configuration Example

With the model details filled in, the configuration looks something like this:

            
[

            
  {

            
    "name": "Azure",

            
    "vendor": "azure",

            
    "apiKey": "${input:chat.lm.secret.-15291caa}",

            
    "models": [

            
      {

            
        "id": "gpt-5.6-luna",

            
        "name": "gpt-5.6-luna",

            
        "url": "https://<foundry-instance-name>.services.ai.azure.com/openai/v1/responses",

            
        "toolCalling": true,

            
        "vision": true,

            
        "thinking": true,

            
        "maxInputTokens": 128000,

            
        "maxOutputTokens": 16000,

            
        "editTools": [

            
          "apply-patch",

            
          "code-rewrite",

            
          "multi-find-replace",

            
          "find-replace"

            
        ]

            
      }

            
    ]

            
  }

            
]

            

The apiKey value is a reference generated by VS Code. Your value will therefore be different from the one shown above.

The token limits in this example are also just configuration values for this particular model. Make sure you use values that match the model you have deployed.

If you have several models deployed in the same Microsoft Foundry resource, simply add more model objects to the models array.

When you are done, press Ctrl + S to save the configuration. Your Foundry model should now be available in the model picker in the VS Code Chat view.

Configure the Utility Models

VS Code uses separate utility models for some background AI tasks instead of the model you have selected in the Chat view. These tasks include generating titles, commit messages, branch names, and other lightweight operations.

To configure these models, open the Command Palette with Ctrl + Shift + P and run:

Preferences: Open User Settings

image-7

In the Settings dialog, search for utility model .

image-8-1024x451

You should see the following two settings:

• Chat: Utility Model
• Chat: Utility Small Model

Select the Microsoft Foundry model you configured earlier for both settings.

For my setup, I use GPT-5.6 Luna for both. It is fast, capable, and well suited for smaller tasks such as generating commit messages.

The two settings actually serve slightly different purposes. Chat: Utility Model is used for general utility tasks such as summaries, settings search, and Git review. Chat: Utility Small Model handles faster and lighter tasks such as commit messages, branch names, rename suggestions, and intent detection.

Configure Default Models for Different Tasks

You can also configure which model VS Code should use by default for different AI tasks. For instance, you might want to use one model for planning and another for everyday utility tasks.

Open User Settings again and search for default model :

image-9-1024x656

VS Code will show settings where you can select default models for different tasks and agents. For example, the Plan agent has its own default model setting.

For my setup, I can use GPT-5.6 Terra as the default model for planning while keeping GPT-5.6 Luna as the faster and more cost-effective model for everyday utility tasks.

This gives you quite a bit of flexibility. You don’t have to use the same model everywhere. You can use a fast and inexpensive model for routine work and reserve a more capable model for tasks where the additional reasoning is actually useful.

Common Questions

Do I Still Need a GitHub Copilot Plan?

Not necessarily.

VS Code supports BYOK models for Chat and utility tasks without signing in to GitHub and without a GitHub Copilot plan. However, BYOK does not replace every Copilot feature. Standard inline code completions, semantic search, and features that depend on embeddings still require GitHub Copilot.

If your main use case is interacting with AI through the VS Code Chat interface, your own Microsoft Foundry models can therefore cover a significant part of your everyday AI usage.

Can I Configure More Than One Microsoft Foundry Resource?

Yes. You can create separate Azure model groups in VS Code for different Microsoft Foundry resources.

This can be useful if you want to separate usage between different Azure subscriptions, customers, or internal cost centers.

Can I Configure Several Models From the Same Foundry Resource?

Yes. Simply add multiple model definitions to the models array for the same Azure group.

This is how I configure different models for different purposes. For instance, I use GPT-5.6 Luna for most everyday tasks and GPT-5.6 Terra when I need a bit more reasoning power.

Do I Have to Use the Same Model Everywhere in VS Code?

No. You can configure different models for different tasks.

You can select a model directly from the VS Code Chat model picker, configure separate utility models, and define default models for specific agents and tasks.

Summary

Using your own models from Microsoft Foundry with GitHub Copilot in VS Code gives you a lot of flexibility without changing the development environment you are already familiar with.

You can choose the models you want to use, pay for the model usage through Azure, configure different models for different tasks, and even separate usage between different Foundry resources and Azure subscriptions.

For me, this has turned out to be a very practical setup. I get to keep the GitHub Copilot experience in VS Code that I already like, while having much more control over which models I use and how that usage is billed.

If you mainly use AI as a power tool to help you work faster, rather than relying on autonomous cloud-based development features, using your own Microsoft Foundry models with GitHub Copilot in VS Code is definitely worth trying.

About Me

I am a Lead Cloud Architect based in Helsinki, Finland, specializing in Microsoft Azure, Microsoft 365, enterprise cloud architecture, automation, identity, and modern Microsoft technologies. I have worked professionally with Microsoft technologies since the mid-1990s and started working with Azure and Office 365 before they reached general availability.

My work focuses on designing secure, scalable, and maintainable systems based on Microsoft cloud technologies. I work extensively with Azure services, Microsoft 365, automation, identity and access management, C#, and .NET, helping organizations apply these technologies in ways that are practical, maintainable, and valuable in everyday operations. My approach combines long-term architectural thinking with hands-on implementation experience.

At Integrata Oy , I design and develop Azure-based systems and Microsoft 365 integrations that support payroll and HR services. My role combines cloud architecture, software engineering, automation, and system integration to create practical solutions for business-critical processes.

In 2021, I founded Denomica Oy , through which I provide consulting, architecture, and development services focused on Microsoft cloud technologies and modern Azure-based solutions. Through Denomica, I also explore emerging Microsoft cloud capabilities, particularly around automation, identity, and AI, while contributing to open-source and experimental projects.

I am particularly interested in how modern cloud platforms, automation, and AI can improve the way organizations use and manage information across systems and processes.

My professional background spans several decades across cloud architecture, enterprise systems, software development, and Microsoft technologies. During my career, I have worked at companies including Visual Systems , Tieto , Sininen Meteoriitti , Develore , Valtti Kumppanit , and Integrata . Earlier in my career, I also gained experience in the retail, energy production, and industrial construction industries, which gave me valuable insight into how technology supports real-world operations.

Outside work, I contribute to open-source projects on GitHub and write about cloud architecture, Microsoft technologies, AI, automation, semantic technologies, and modern software development on this blog.

If you would like to discuss Azure, Microsoft 365, cloud architecture, integrations, automation, or system design, feel free to reach out and network with me on GitHub or LinkedIn .

Blazorade Scraibe: Making Blazor Content Discoverable

May 2, 2026

If you’ve ever built a Blazor WebAssembly application with real content, you may have run into a frustrating problem. Everything works in the browser, but search engines and AI tools struggle to see your content.

The reason is simple. Your content does not exist until the application runs in the browser.

This is not specific to Blazor. The same issue affects all Single Page Application (SPA) frameworks, including React , Angular , and Vue . The initial HTTP response only returns bootstrap logic, and JavaScript renders the actual content later. Many bots and AI agents never execute that step. They fetch the HTML, see an empty shell, and move on.

At the same time, something else has changed. With tools like GitHub Copilot , you are no longer building alone. You can treat Copilot as a relentless site builder that helps you write content, structure pages, and build components as you go.

Blazorade Scraibe is built around that idea. It combines static content generation with a set of conventions and guidance that work well with Copilot, so you can generate content, structure your site, and build interactive components with its help.

Blazorade Scraibe is an ongoing project. Features evolve based on real-world use, community contributions, and my own work on improving the project.

The Problem With SPA Applications and Content Visibility

How SPA Applications Work

Blazor WebAssembly , React , Angular , and other SPA frameworks all follow the same basic model. When a browser requests a page, the server returns a minimal HTML document along with JavaScript that bootstraps the application. The application then runs in the browser and renders the actual content.

This approach works well for users. It gives you fast navigation, rich interactivity, and a smooth experience overall. But it also shifts where the content exists. Instead of being part of the initial response, the content only appears after the application has started running in the browser.

What Bots and AI Agents Actually See

This difference becomes obvious when something other than a browser accesses your site. When a bot sends an HTTP request, it typically only reads the initial HTML response and does not execute any JavaScript.

In that situation, the bot never sees the rendered content. It only sees the application shell. From its point of view, the page is mostly empty, even though a real user would see a fully rendered view a moment later.

You can test this yourself. Try loading any page from your SPA application using tools like Postman or Bruno and look at the response. It will not match what you see in the browser. Then try the same with the Blazorade Scraibe documentation site . That site runs as a Blazor WebAssembly application on Azure Static Web Apps , even on the free tier, but still returns fully readable content in the initial response.

Why This Matters

For applications that focus purely on functionality, this may not be a big issue. But as soon as your application contains content that you want others to find, things change.

Search engines rely on readable HTML to index your pages. AI tools rely on content they can directly read and process. If your content is not present in the initial response, it becomes much harder for these systems to understand and use it. The result is reduced visibility, weaker indexing, and less reliable previews.

This Is Not a Blazor Problem

It is worth being clear about one thing. This is not a limitation of Blazor. It is a direct consequence of client-side rendering.

You will see the same behavior in React , Angular , Vue , and any other framework that renders content in the browser. If the content is not part of the initial HTML response, it remains invisible until something executes the code.

Typical Solutions and Their Trade-offs

Once you run into this problem, there are a few ways to address it. Each of them solves the visibility issue, but they come with different trade-offs.

Server-Side Rendering (SSR)

One common solution is to move rendering to the server. With server-side rendering in Blazor , the server generates HTML before sending the response. This ensures that both users and bots receive fully rendered content.

This approach solves the visibility problem, but it changes the nature of the application. You now depend on a server to handle every request, which adds complexity and introduces a different cost model. As traffic grows, so does the need to scale your backend.

For many applications, this is a perfectly valid trade-off. But if your goal is to keep the simplicity of static hosting, it may not be the ideal fit.

Static Site Generators

Another option is to move away from SPA rendering entirely and generate static HTML using tools like Hugo or Docusaurus . These tools produce fully rendered pages at build time, which makes the content easy to index and process.

This solves the discoverability problem without requiring a server at runtime. The trade-off is that you lose the native interactivity of a Blazor application. Adding dynamic behavior becomes harder, and you often end up mixing different technologies to get the same level of functionality.

The Blazorade Scraibe Approach

Blazorade Scraibe takes a different approach to the problem. Instead of rendering content on every request, or relying entirely on client-side rendering, it generates the content ahead of time and serves it as static HTML.

The idea is simple. Generate the content at build time, and use Blazor at runtime to enhance the experience.

During the build process, Blazorade Scraibe converts your content into static HTML pages. That content becomes part of the initial HTTP response, which means search engines and AI tools can read it directly without executing any JavaScript.

Each generated page also acts as a bootstrapper for the Blazor WebAssembly application. No matter which page you load, it already contains both the rendered content and the logic required to start the application.

You can observe this in practice on the Blazorade website . When you reload the front page, you briefly see the static content. It then clears and shows a “loading…” message while the Blazor app initializes, before rendering the final interactive view.

What makes this approach especially interesting today is how it fits with tools like GitHub Copilot . Instead of manually wiring everything together, you can use Copilot to help you write content, structure pages, and build components as you go.

Blazorade Scraibe leans into that workflow. It provides a structure and a set of conventions that work well with Copilot, so you can treat it as a kind of site builder that helps you move faster without losing control.

In practice, this means you can focus more on the content and the experience, and let the tooling help you with the repetitive parts.

Core Features of Blazorade Scraibe

Blazorade Scraibe is built around a few core ideas that work together to solve the discoverability problem while keeping the flexibility of a Blazor application.

GitHub Copilot as a Site Builder

Blazorade Scraibe is designed specifically for GitHub Copilot . In this context, Copilot becomes more than a coding assistant. It acts as a site builder that helps you create content, structure your site, and build components as you go.

Instead of manually wiring everything together, you describe what you want. Copilot helps you generate pages, organize content, and implement components that fit into the Scraibe structure. You are not starting from a blank page, and you are not working alone.

This changes how you approach building content-driven sites. You focus on the content and the experience, while the tooling helps you move faster and stay consistent.

Static Content Generation

At the core of Scraibe is static content generation. During the build process, your content is converted into HTML and included directly in each page.

This ensures that the full content is available in the initial response. Search engines and AI tools can read it without executing any JavaScript, which makes the content discoverable and usable outside of the browser.

Content-First Structure

Scraibe uses a content-first approach based on Markdown and a simple folder structure. Pages are defined as files, and sections are defined by folders.

This keeps the content easy to organize and maintain, while also making it straightforward to understand how the site is structured.

Designed for Azure Static Web Apps

Blazorade Scraibe is primarily designed to run as a static site in Azure Static Web Apps . This gives you a simple deployment model with global distribution and low hosting costs.

You can host it elsewhere, but Azure Static Web Apps is a natural fit for this type of application.

Shortcodes for Blazor Components

You add Blazor components to your Markdown content through shortcodes.

A shortcode is a placeholder in your content that represents a full-featured Blazor component. When the application runs, Scraibe replaces that shortcode with the component it points to. That component can be something simple, like a button or carousel, or something much more advanced, like a form or an interactive tool that connects to a backend.

This approach keeps your content clean and easy to work with, while still giving you the full power of Blazor wherever you need it.

An Evolving Project

Blazorade Scraibe is an ongoing project. Features are added as they are needed, driven by real-world usage, community contributions, and continuous development.

Key Questions About Blazorade Scraibe

When is Blazorade Scraibe a good fit?

Blazorade Scraibe works well when your application contains content that you want others to find and read.

Typical use cases include documentation sites, developer portals, blogs, campaign sites, and company websites, especially for smaller companies. It is a strong fit when you want to combine discoverable content with the flexibility and interactivity of a Blazor application.

When is it not a good fit?

If your application is primarily focused on functionality and contains little or no static content, Scraibe may not add much value.

The same applies to highly dynamic dashboards or applications that depend heavily on real-time data. In those cases, rendering content ahead of time does not provide much benefit.

It is also not a strong fit for applications where content is only available to authenticated users. Since that content is not accessible to search engines or AI agents anyway, generating static versions of it does not add much value.

It is also worth noting that SPA applications do not protect content simply by hiding it behind client-side logic. If the content is part of the application bundle, it is already available in the browser, even if it is not rendered. Content that should only be available to authenticated users must be retrieved from a backend, for example through a REST API that requires a valid access token.

Why not just use Blazor SSR?

Server-side rendering in Blazor solves the visibility problem by rendering HTML on the server before sending it to the client.

That approach works well, but it introduces a server into the architecture. This increases complexity and changes the cost model as your traffic grows. If you want to keep the simplicity of static hosting, it may not be the best fit.

How does this compare to static site generators?

Tools like Hugo and Docusaurus generate static HTML at build time, which makes content easy to index and distribute.

Blazorade Scraibe takes a similar approach to content generation, but keeps the application in Blazor and is designed specifically for use with GitHub Copilot .

With traditional static site generators, you typically write content and templates manually, and the tooling focuses on transforming that into static output. With Scraibe, you can use Copilot as a site builder that helps you create content, structure your site, and build interactive components directly within the same workflow.

This means you are not just generating static pages. You are building a Blazor application where content and interactivity evolve together, with Copilot assisting you throughout the process.

Can you mix static and interactive content?

Yes.

Static content forms the foundation, and you add interactivity where needed using shortcodes that map to Blazor components. This lets you keep content simple while still building more advanced features when required.

Is Blazorade Scraibe tied to Azure?

In practice, yes.

While Blazor WebAssembly itself is not tied to any specific platform, Blazorade Scraibe is designed with Azure Static Web Apps in mind. For example, it generates the staticwebapp.config.json configuration file, which is specific to that platform.

It is possible to adapt it to other hosting environments, but Azure Static Web Apps provides the most natural fit and the least friction.

Is Blazorade Scraibe tied to GitHub Copilot?

In practice, yes.

Blazorade Scraibe is designed specifically for use with GitHub Copilot . The structure, conventions, and workflows are built to work well with Copilot as a site builder.

You can use it without Copilot or with another coding AI agent, but you will need to review the structure, conventions, and workflows to make sure they align with the tool you choose. Much of the value comes from how Copilot helps you create content, structure your site, and build components as you go.

How can you contribute or extend it?

You can start by using it in your own projects and adapting it to your needs.

If you want to contribute back, you can submit pull requests to the Blazorade Scraibe repository or participate in discussions around new features and improvements.

Summary and Key Takeaways

Blazor WebAssembly applications, like other SPA frameworks, render content in the browser. That works well for users, but it also means that search engines and AI agents often never see the actual content.

Blazorade Scraibe solves this by generating static content at build time. The content becomes part of the initial response, while the Blazor application still provides interactivity in the browser.

At the same time, it embraces a different way of building sites. With GitHub Copilot , you are no longer working alone. Scraibe is designed so that Copilot can act as a site builder, helping you create content, structure your site, and build components as you go.

This gives you a practical middle ground:

• Content that is readable and discoverable
• A full Blazor application for interactivity
• A workflow where Copilot helps you move faster and stay consistent

Blazorade Scraibe works well for content-driven sites such as documentation, blogs, campaign pages, and company websites. It is especially useful when you want to combine discoverable content with the flexibility of building in Blazor.

If you want to get started, you can create a new project by clicking the button below.

Create your new repository here

Also have a look at my other Blazorade and Blazor articles to read more.

Protecting APIs with Microsoft Entra ID

December 13, 2025

In this article I describe a practical approach to protecting APIs with Entra ID. The goal is to configure your app registrations so that your API app gets the information it needs to make solid authorization decisions for each request. Entra ID provides that information through app roles and scopes, and your API app can rely on these when the setup is clean.

I use two simple applications named Web app and API app to keep the examples concrete. This pattern is common and shows how an application can act on behalf of a user. In that scenario the API app must understand what the user can do and what the application can do for the user. Entra ID supports this model out of the box when the app registrations match the requirements.

This article walks through the structure behind protecting APIs with Entra ID and shows how the OAuth authorization flows enable it. The result works the same way whether a Web app, a background service, or an AI agent calls your API.

Remember also to have a look at my other Microsoft Entra ID articles .

Overview

When you build an API that serves data or functionality to different applications, you want the API app to get the information it needs to make solid authorization decisions for every request. In Microsoft Entra ID, this information comes from app roles and scopes. When structured well, they give the API app a predictable model for deciding whether a request should be allowed or denied.

Here is how the flow works:

1. The Web app asks Entra ID for an access token with one or more scopes.
2. Entra ID returns a token that contains both the scopes the user granted and the user’s assigned app roles.
3. The Web app calls the API app and includes the access token.
4. The API app verifies that Entra ID issued the token.
5. The API app reads the app roles and scopes from the token and derives what is allowed for this request.
6. The API app performs the action or denies it.

This structure gives the API app a clear and consistent way to enforce authorization using only information from the token. It is also a practical foundation for protecting APIs with Entra ID in real systems.

What Is the Difference Between App Roles and Scopes?

App roles and scopes both describe permissions in Entra ID, but they serve different purposes. App roles define what a user or an application can do in the API app. Each role represents one action or a set of actions. When you assign a role to a user, a group, or an application, you set the limits for what that identity can do.

Scopes describe what the Web app may do on the user’s behalf. The Web app requests scopes during the OAuth flow, and the user can grant or deny them. Inside the API app, scopes tell you what permissions the user has delegated to the Web app for this specific call.

The two signals work together. App roles set the hard limits for what the user or application is allowed to do. Scopes narrow down which of those allowed actions the Web app can take for the user. Scopes never expand permissions.

App roles answer: What is this user or application allowed to do at all? Scopes answer: What has the user allowed this Web app to do for them in this call?

When the request reaches the API app, the user must hold the right role and the caller must present the right scope. This pattern forms the core of protecting APIs with Entra ID.

Creating the App Registrations

Everything starts with the app registrations. The API app defines the permission model with its app roles and scopes. The Web app asks for those permissions when it calls the API. Both registrations must line up so that Entra ID can issue tokens that the API app can trust.

In the next sections we create the two registrations and look at the settings that matter for authorization.

API App Application Registration

We start by creating the app registration for the API app. Then we add app roles to it. These roles define what the user or the calling application can do. Each role represents an action or a set of actions. You can choose whether a role can be assigned to users and groups, to applications, or to both. Make this choice early, since it shapes how the API app is meant to be used.

Next, expose the API. Set the Application ID URI to identify the API app as a resource. Then define at least one scope. In this example we add the user_impersonation scope. Calling applications request this scope when they want to act on behalf of a user with the permissions that the user already has, i.e. the app roles the user has been assigned to through direct assignment or group membership.

Add any additional scopes the API app needs. Scopes describe what the calling application wants to do for the user. The API app uses them to understand the caller’s intent.

The API app holds the full definition of its permission model. This keeps the structure predictable and sets the baseline for the Web app registration.

Web App Application Registration

Create a second app registration for the Web app. This registration represents the Web app that calls the API app on behalf of the user. Configure the platform settings so the Web app can sign users in and request tokens from Entra ID.

Next, give the Web app access to the API app. Add the delegated permission that corresponds to the user_impersonation scope you created earlier. The Web app requests this scope during the OAuth flow when it needs to act for the user. The user can grant or deny this permission, depending on how the application is used. You can also add the Web app as a trusted application to the API app. Users are not asked for consent to trusted applications.

The Web app does not define app roles. All roles belong to the API app, because all actions that need protection happen in the API app. The Web app is just the UI to the functionality exposed by the API app. The Web app only asks for the scopes it needs, and it relies on Entra ID to include the user’s app roles in the access token that it receives.

With both app registrations in place, we can move on to assigning app roles to users, groups, and applications.

Assigning App Roles to Users, Groups, and Applications

Once the API app defines its app roles, you can start assigning them to the identities that need access. You can assign a role directly to a user, to a security group, or to an application. The choice depends on how you want to manage access.

Assigning a role directly to a user gives that user the permissions described by the role. This works for small setups, but it does not scale well. Assigning roles to security groups works better. You place users into groups that represent your access model, and the API app receives the user’s effective roles in the access token.

Some roles are intended only for applications. These roles describe what an application can do when it calls the API as itself. Assign the role directly to the calling application.

When the Web app calls the API on behalf of a user, the access token includes the roles the user holds, either through direct assignments or group memberships. When a background service calls the API as itself, the token includes the roles assigned to that application. In both cases, the API app receives the information it needs to understand what the caller is allowed to do.

Authorization Inside the API App

When a request reaches the API app, it carries an access token from Entra ID. That token contains app roles, scopes, and other claims. The API app uses these to decide what the caller is allowed to do and should rely on the token as much as possible. This model is a core part of protecting APIs with Entra ID.

How to Use App Roles for Authorization?

App roles describe what a user or an application can do in the API app. These roles map directly to the functionality the API exposes. When the Web app calls on behalf of a user, the token contains the user’s roles. When a background service calls as itself, the token contains the roles assigned to that application. The API app checks these roles to see if the caller may perform the requested action.

You should design your app roles to match how you talk about access in the system. If the API exposes operations for reading and writing data, then roles should reflect those capabilities. The API app then checks for the required role before it performs an operation.

How to Use Scopes for Delegated Permissions?

Scopes describe what the Web app may do on the user’s behalf. During the OAuth flow, the Web app asks for one or more scopes, and the user can grant or deny them. When the user grants a scope, the user delegates a subset of their permissions to the Web app.

Inside the API app, scopes tell you what the user has allowed the Web app to do in this specific call. Scopes do not change what the *user * is allowed to do in general. They only limit what the Web app can do for the user. The API app uses the scopes in the token to understand how far the Web app may act on the user’s behalf.

How to Derive Allowed Actions from App Roles and Scopes?

The API app derives the allowed actions by applying the scopes to the user’s roles. The user must hold the role for the action. The Web app must hold a scope that lets it act for the user for that same action.

App roles and scopes must have unique names inside the API app’s registration, so you cannot name a scope the same as a role. Because of this, the API app needs a simple way to map scopes to the roles that apply for a request. Entra ID does not provide a built-in mapping mechanism. A static mapping in the API app usually works well. App roles and scopes change rarely, so a static structure does not add much maintenance.

For example, a scope named Profile.Manage.My could map to several app roles, such as Account.Read.My , Account.Write.My , ContactInfo.Read.My , ContactInfo.Write.My , and ContactInfo.Delete.My . When a request arrives, the API app looks at the scopes included in the access token and uses its mapping to determine which app roles apply for this call. It then compares that set with the roles the user actually holds. Any role in the mapping that the user does not have is not included in the effective permissions for this request.

The API app checks both signals for each request and then performs or denies the action.

A Practical Example: A CRM Application Protecting Its APIs with Entra ID

To illustrate how app roles and scopes work together, let’s look at how this could be implemented in a simple CRM application. The CRM system exposes its functionality through an API app. A Web app provides the user interface and calls the API on behalf of the user.

The API app includes operations for managing accounts, contacts, and proposals. These operations must be protected so that users and applications can access only what they are allowed to.

Example App Roles

The API app defines these app roles:

• Accounts : Accounts.Read.Team , Accounts.Read.All , Accounts.Write.Team , Accounts.Write.All
• Contacts : Contacts.Read.My , Contacts.Read.Team , Contacts.Read.All , Contacts.Write.My , Contacts.Write.Team , Contacts.Write.All
• Proposals : Proposals.ReadWrite.Team , Proposals.ReadWrite.All

These roles reflect the functionality the CRM API exposes and follow a simple constraint model:

• My : actions on objects owned by the user
• Team : actions within the user’s team or department
• All : actions across the entire tenant

This keeps the permission model predictable while still giving the CRM system enough flexibility for everyday scenarios. Users gain access through direct role assignments or group membership. Background services can also be assigned roles when calling the API as themselves.

Example Scopes

The API app exposes the following scopes:

• CRM : Crm.Read.My , Crm.Read.Team , Crm.Read.All , Crm.ReadWrite.My , Crm.ReadWrite.Team , Crm.ReadWrite.All
• Sales : Sales.ReadWrite.Team , Sales.ReadWrite.All

The CRM scopes map to the Accounts and Contacts roles:

• Crm.Read.* maps to the read roles for Accounts and Contacts with the same suffix.
• Crm.ReadWrite.* maps to both read and write roles for Accounts and Contacts with the same suffix.

The Sales scopes map to the Proposals roles:

• Sales.ReadWrite.Team maps to Proposals.ReadWrite.Team .
• Sales.ReadWrite.All maps to Proposals.ReadWrite.All .

At runtime, the API app uses this mapping together with the user’s app roles in the access token. The scopes tell the API app what the user has allowed the Web app to do. The app roles tell the API app what the user is actually allowed to do. The intersection of the two becomes the effective permissions for the request.

End-to-End Example

1. The user signs in to the Web app.
2. The Web app requests an access token for the API app and includes Crm.ReadWrite.Team .
3. Entra ID issues a token containing the scopes the user granted and the app roles assigned to the user.
4. The Web app calls the CRM API and includes the access token.
5. The API app verifies that Entra ID issued the token.
6. The API app looks at the user’s app roles to understand what the user is allowed to do.
7. The API app looks at the scopes in the token to understand what the user has allowed the Web app to do for them.
8. The API app uses its internal mapping to translate Crm.ReadWrite.Team into the corresponding Accounts and Contacts roles: Accounts.Read.Team , Accounts.Write.Team , Contacts.Read.Team , Contacts.Write.Team .It then intersects this set with the roles the user actually holds.
9. The API app derives the effective permissions for the request.
10. The API app performs the action or denies it.

This example shows how roles and scopes work together in a real CRM system. The app roles define what the user or an application may do. The scopes define what the user allows the Web app to do on their behalf. The API app derives the effective permissions by applying one to the other and then makes a clear authorization decision.

Summary

Protecting APIs with Entra ID works best when the Web app and the API app follow a clear structure. The API app should rely on the access token as much as possible. The token carries what the API needs for authorization, including the user’s app roles and the scopes the user has granted to the Web app.

App roles define what the user or an application is allowed to do in the API app. Scopes define what the user allows the Web app to do on their behalf in a specific call. Roles and scopes must have unique names, and the API app must implement the mapping between them. The API app then derives the effective permissions by intersecting the user’s app roles with the roles implied by the granted scopes. This gives the API app predictable and secure authorization decisions without extra custom layers.

A clean set of app registrations, a simple mapping model, and a consistent authorization approach inside the API provide a solution that is easy to understand, easy to maintain, and flexible enough for most real systems. This pattern gives you a solid and repeatable way of protecting APIs with Entra ID in real applications.

References

• Add app roles and get them from a token
• Configure an application to expose a web API
• Verify scopes and app roles in a protected web API
• OAuth 2.0 Authorization Framework (RFC 6749)
• OpenID Connect Core Specification
• Understanding OAuth 2.0 Scopes

From Words to Meaning: The Rise of Vector Search in Cosmos DB

November 7, 2025

Modern search is shifting from looking at words to understanding meaning. Traditional indexing and search have worked well for decades, but they were designed for documents and keywords, not natural language. When users ask questions, paraphrase content, or mix languages, old search models struggle.

With Cosmos DB Vector Search , Microsoft brings semantic understanding directly into the database. Instead of matching words, it measures similarity of meaning . This article explains how traditional word-based search works, why it often fails for natural language, and how vector search changes the game.

Introduction

Traditional search engines depend on rules. They split text into words, remove noise, and match tokens. It’s efficient, but mechanical.

Cosmos DB’s Vector Search for NoSQL API introduces a completely different approach. It represents content as vectors, arrays of numbers that capture the semantic context of words, sentences, or entire documents. Similar meanings are stored close to each other in multidimensional space.

This article compares these two approaches and explains why vector-based similarity search is better suited for natural language and AI-powered applications.

How Traditional Search Works

Before understanding why vector search matters, it helps to know how traditional search functions.

Most search engines use inverted indexes . They break text into tokens, often using word breakers and analyzers . Each unique word points to a list of documents that contain it. To improve accuracy, search systems also use stemmers and lemmatizers that reduce words to their root forms.

• “driving”, “driven”, and “driver” are reduced to “drive”
• “cats” and “catlike” both relate to “cat”

When you search for “renew car insurance” , the engine looks up “renew”, “car”, and “insurance” in the index. It might find “renew car insurance policy” but miss “automobile coverage renewal”. The reason is simple, the system compares words, not meanings.

Traditional systems work well for structured or predictable text, such as product names, SKUs, or codes. But they fail when wording changes or when people use synonyms.

Where Keyword Search Falls Short

Word-based indexing is fragile. It relies on exact matches and does not understand context.

• “How to reset password” vs. “forgot login credentials”
• “car insurance” vs. “automobile coverage”
• “apple” as a fruit vs. “Apple” as a company

A word-based system cannot tell that these phrases are semantically close. Even with advanced analyzers, it still matches on form, not intent.

In multilingual contexts, the problem grows. A Finnish query like “vaihda salasana” would never match an English document titled “reset password instructions” without translation or manual mapping.

This is where similarity search provides a better model.

Understanding Vector Search

Instead of storing words, vector search stores vector embeddings . These are fixed-length numeric arrays that represent the meaning of text.

Each vector is a list of floating-point numbers. The distance between two vectors shows how similar their meanings are. Closer vectors mean more similar content.

You can think of a vector as a path through a landscape of meanings. Each point along the path represents a topic or concept found in the text. If another path runs close to it or even crosses it, then the content that the second path represents is likely similar to the first. This is what similarity search looks for, paths that travel close together in meaning.

For example, vectors generated from “how to reset password” and “forgot login credentials” will be close together in vector space, even though they share no words.

Embeddings are created using AI models such as text-embedding-3-small or text-embedding-3-large . These models turn text into a mathematical representation of its meaning.

Once stored, these embeddings make it possible to run similarity searches that find items with vectors close to a given query vector.

How Cosmos DB Vector Search Works

Cosmos DB now supports storing and searching vector embeddings directly inside your NoSQL containers. The feature is available under the Vector Search for NoSQL API .

You enable it by defining a vector policy when creating a container. The policy specifies:

• The JSON path to the embedding array
• The data type (usually float )
• The number of dimensions (for example, 1536 for text-embedding-3-small )
• The distance function to use (typically cosine similarity )

After embeddings are stored, you can use the built-in VectorDistance() function in SQL queries to find semantically similar documents.

            
SELECT TOP 5 c.id, c.content, VectorDistance(c.embedding.vector, @queryVector) AS similarity

            
FROM c

            
WHERE c.partition = 'help-articles'

            
ORDER BY VectorDistance(c.embedding.vector, @queryVector)

            

This query returns the five most similar documents to the query vector. You can combine similarity search with metadata filters such as customer ID or region, just like any other Cosmos DB query.

You can find a step-by-step walkthrough of how to enable and configure this feature in my earlier article Cosmos DB Vector Search – An Introduction .

This makes it easy to mix semantic ranking with structured filtering in the same data store.

Why Vector Search Fits Natural Language

Vector embeddings capture the meaning of language rather than its exact form. This makes them ideal for unstructured, user-generated, or multilingual data.

• Semantic understanding: Matches content with similar intent, even with no shared words.
• Synonym and paraphrase tolerance: Recognizes “cancel booking” and “terminate reservation” as related.
• Language agnostic behavior: Similarity depends on meaning, not language.
• Contextual clustering: Similar documents naturally group together, simplifying recommendations and content discovery.
• Support for exploratory search: Vector embeddings help you find information even when you are not sure what you are looking for. They surface related concepts and content that might not contain the words you use but still carry the same meaning.

This semantic flexibility makes vector search a perfect fit for AI-driven scenarios such as:

• RAG (Retrieval-Augmented Generation) pipelines
• Chatbots and virtual assistants
• Knowledge bases and document search
• Product and content recommendations

When to Use Keyword Search and When to Use Vector Search

Keyword and vector search complement each other.

| Use Keyword Search | Use Vector Search | | --------------------------------------- | --------------------------------------------- | | When you need exact matches or codes | When queries are phrased naturally | | When data is structured and predictable | When language is varied or unstructured | | For short or technical terms | For synonyms, paraphrases, and long-form text | | For strict filters and sorting | For finding semantically similar documents |

You can also combine both approaches. A hybrid search first narrows down documents with keywords or metadata, then re-ranks the results using vector similarity. This gives the accuracy of filtering with the intelligence of semantic matching.

Building a Simple Similarity Search Flow

1. Generate embeddings for your text using Azure AI Foundry .
2. Store documents and their embeddings in a Cosmos DB container with a vector policy.
3. When a user submits a query, generate a query vector using the same embedding model.
4. Run a Cosmos DB SQL query with VectorDistance() to find the most similar documents.
5. Optionally combine with structured filters or use the results in a downstream AI model.

This simple flow powers applications that need fast, semantically aware search without moving data to a separate vector database.

Common Questions and Answers

Why not just use full-text search?

Full-text search matches exact words or phrases. It is fast and works well for technical or structured text. However, it fails to capture meaning. Vector search complements it by handling natural language and synonyms.

Do I need a separate AI service to create vectors?

Yes, you need an embedding model such as text-embedding-3-large deployed in Azure AI Foundry . The model transforms text into a numeric vector that you then store in Cosmos DB.

Can vector search handle multiple languages?

Yes. Vector search can be language agnostic because embedding models capture the semantic meaning of text, not the literal words or language used.

Should I replace all keyword searches with vector search?

No. Use keyword search for identifiers or precise filters. Use vector search for meaning-based retrieval or conversational AI. They work best together.

Summary

Traditional search engines match words. Vector search matches meaning.

By storing and querying embeddings directly in Cosmos DB, developers can build applications that understand language, not just text. The same system can now support both structured and semantic queries, making Cosmos DB a powerful choice for AI-driven solutions.

Cosmos DB Vector Search lets you move from searching by words to searching by intent. It is a small change in how data is stored, but a big step toward systems that understand human language.

References

• Vector Search in Azure Cosmos DB for NoSQL
• Vector Embeddings in Azure Cosmos DB
• Azure AI Foundry Embedding Models
• Cosmos DB Vector Search – An Introduction
• Vector Embedding Model Comparison with Multilingual Text

Keyed Services Not Supported in Azure Functions

September 22, 2025

A while ago I was working on an Azure function application, and ran into a very weird problem. Suddenly I started getting a pretty confusing error, that actually pointed me away from the correct solution. The error I got was the following.

            
Expecting the instance to be stored in singleton scope, but unable to find anything here.

            
Likely, you've called UseInstance from the scoped container, but resolving from another container or injecting into a singleton.

            

If you are looking for a solution to a similar error, you’ve come to the right place.

Initial Troubleshooting

In my function application, I have quite a few services registered. Many of them depend on other services. So at first I thought that this is an easy case, and I have tried to inject a scoped or transient service into a singleton service. So I started to dig deeper into my dependency chains for my services. But even after digging around for several hours, I could not find anything that would help me solve the problem. Finally I ended up registering all my services as singleton services, just to make sure that I am not injecting a scoped service into a singleton service. Guess what, I still got the same error.

Reproducing the Problem

Before I reveal the solution, which you probably already guesses from the title of this article, I’ll talk a bit about how to reproduce the problem. I’ve created a Github repository that contains code that demonstrates how you can reproduce this problem.

Note! This problem affects only Azure function applications that use the in-process worker model. Isolated worker model is not affected. So, this problem will probably go away during the coming year, since the in-process worker model will run out of support in November 2026.

One of the things that made this so tricky for me to resolve was that fact that I did not need keyed services in my application. I just used another library that we use in many different kinds of applications, which itself registers keyed services. If I would have injected a keyed service into my functions class using the FromKeyedServicesAttribute attribute, or requested a keyed service using the IServiceProvider.GetKeyedService method, I would have gotten a much more descriptive error message, such as the one below.

            
Anonymously Hosted DynamicMethods Assembly: This service provider doesn't support keyed services.

            

That would have immediately told me where the actual problem is instead of pointing me in the wrong direction trying to find conflicts in my service scopes.

Below is the Configure method from the Startup class in my in-process function app that works.

            
public override void Configure(IFunctionsHostBuilder builder)

            
{

            
    builder.Services

            
        .AddSingleton<SharedServices.MiscService>();

            
}

            

The code below adds one keyed service of the same type as is already in use by the application as a “normal” registered service. This code will throw the exception described in the introduction of this article. Even if you don’t even use the keyed service.

            
public override void Configure(IFunctionsHostBuilder builder)

            
{

            
    builder.Services

            
        .AddSingleton<SharedServices.MiscService>()

            
        .AddKeyedSingleton<SharedServices.MiscService>("foo")

            
        ;

            
}

            

The Problem – Keyed Services

As you probably guessed, the cause for the problem was keyed services. The in-process worker model in Azure functions does not support keyed services. I am writing this article in September 2025. Support for the in-process worker model will run out of support in November 2026. So I don’t expect this to be fixed in the in-process worker model. It is not a security related or otherwise a critical problem. As you can see from my code sample , this is not a problem in isolated worker model. I guess the official story is that if you need keyed services, you need to migrate to isolated worker model.

Further Reading

Over the years, I’ve come across several problems with Azure functions that have been quite tricky to resolve. You can read more about them in my other Azure functions articles .

Simplify Text Chunking for Vector Embeddings

August 17, 2025

Text chunking is crucial when working with vector embedding models , no matter where you host them. In my previous article, Vector Embedding for Long Documents , I explored how to combine multiple vectors into one. In this post, I’ll share sample code for how to do both chunking long text and combining multiple vectors into one. With the help of Denomica.OpenAI.Extensions , which is published on NuGet , this task is a breeze. This library is built specifically for use with Azure AI Foundry and designed to be both simple and extensible. The source code for this library is also available on Github . If you like this library and find it useful, I would appreciate if you would give the repository a star.

Text Chunking and Vector Embedding

Before we dive into code, let’s have a few words about why text chunking is so important when dealing with vector embeddings. All embedding models, or at least the ones I know of, have limits on how much text they can process. So, if your text exceeds this limit, you have to chunk up your text into smaller parts.

There are a few problems that the Denomica.OpenAI.Extensions library tries to address, in current or future versions.

• Embedding model limits are measured in tokens – not characters, words, or sentences. While tokens can be tricky to estimate, in normal English text a token typically averages around four characters.
• Because of these limits, you have to chunk up your text into smaller pieces so that you don’t exceed the limits.
• After chunking up text and generating an embedding for each vector, you typically want to aggregate them into one embedding representing your original text.

The chapters below describe in more detail how Denomica.OpenAI.Extensions addresses these problems.

Text Chunking in Denomica.OpenAI.Extensions

The Denomica.OpenAI.Extensions library provides a mechanism that allows you to register a chunking service that will take care of the chunking. When you use the EmbeddingProvider class to generate embeddings, the registered chunking service is automatically used to chunk up your text. There is one chunking service provided by the library, the LineChunkingService . This service chunks up the text line by line. One chunk can contain several lines of text as long as it does not exceed the maximum configured size of a chunk.

The code below shows how you can register a chunking service and how to use the EmbeddingProvider to generate embeddings.

            
using Denomica.OpenAI.Extensions.Embeddings;

            
using Denomica.OpenAI.Extensions.Text;

            
using Microsoft.Extensions.DependencyInjection;

            

            
var provider = new ServiceCollection()

            
    .AddOpenAIExtensions()

            
    .WithEmbeddingModel((opt, sp) =>

            
    {

            
        opt.Endpoint = $"https://[Your Azure AI Foundry hub name].openai.azure.com";

            
        opt.ApiKey = "[Your API key goes here]";

            
        opt.Name = "[The name of the embedding model deployment]";

            
    })

            
    .WithChunkingService<LineChunkingService>()

            
    .Services.BuildServiceProvider();

            

            
var embeddingProvider = provider.GetRequiredService<EmbeddingProvider>();

            
var embedding = await embeddingProvider.GenerateEmbeddingAsync("Hello World!");

            

Configuring the LineChunkingService

The LineChunkingService chunks up text line by line into chunks that do not exceed the configured length in characters. Most of the embedding models in Azure AI Foundry have a token limit around 8000 tokens. A rough estimate is that one token evaluates to about 4 characters. That would mean that the maximum length of text that can be used for embedding is around 32 000 characters.

The LineChunkingService uses a default limit of 25 000 characters in order to be safely under the 8000 token limit. Of course, this is not the best solution in every case. You can configure this limit to a value that better suits your needs. The code below shows you how to do this.

            
var provider = new ServiceCollection()

            
    .AddOpenAIExtensions()

            
    .WithEmbeddingModel((opt, sp) =>

            
    {

            
        // Configure your embedding model here.

            
    })

            
    .WithChunkingService(sp =>

            
    {

            
        return new LineChunkingService { MaxChunkSize = 10000 };

            
    })

            
    .Services

            
    .BuildServiceProvider();

            

Create Your Own Chunking Service

The Denomica.OpenAI.Extensions library also allows you to write your own chunking service, and register that to be used by EmbeddingProvider. Below is a simple version of a custom chunking service that you can then develop into your own text chunking service.

            
using Denomica.OpenAI.Extensions.Text;

            
using System.IO;

            

            
public class MyCustomChunkingService : IChunkingService

            
{

            
    public int MaxChunkSize { get; set; } = 8000;

            

            
    public virtual async IAsyncEnumerable<string> GetChunksAsync(Stream input)

            
    {

            
        string inputString;

            
        using(var reader = new StreamReader(input))

            
        {

            
            inputString = await reader.ReadToEndAsync();

            
        }

            
    }

            

            
    public async IAsyncEnumerable<string> GetChunksAsync(string input)

            
    {

            
        // Do your chunking logic here.

            
    }

            
}

            

When you have implemented your chunking service, you register it like shown below.

            
var provider = new ServiceCollection()

            
    .AddOpenAIExtensions()

            
    .WithChunkingService<MyCustomChunkingService>()

            
    .Services

            
    .BuildServiceProvider();

            

Aggregating Multiple Vector Embeddings

The EmbeddingProvider automatically uses the configured chunking service to chunk up text. If the chunking service produces more than one chunk, there will also be more than one embeddings generated. It will also automatically use the registered embedding aggregation service to aggregate multiple embeddings into one before returning. If no aggregation service is registered, the default WeightedAverageAggregationService is used.

The WeightedAverageAggregationService uses a weighted average approach to aggregate multiple embeddings into one. This aggregation service uses the total amount of tokens used to produce the embedding as weight. The more tokens consumed, the longer the text typically is, or is otherwise more significant in relation to other embeddings.

Create Your Own Aggregation Service

You can also create your own custom aggregation service and register that to be used instead of the default. The code below shows how to implement your custom aggregation service.

            
using System.Collections.Generic;

            
using System.Threading.Tasks;

            
using Denomica.OpenAI.Extensions.Embeddings;

            

            
public class MyCustomAggregationService : IEmbeddingAggregationService

            
{

            
    public Task<EmbeddingResponse?> AggregateAsync(IEnumerable<EmbeddingResponse>? embeddings)

            
    {

            
        // Implement your aggregation logic here.

            
        return null;

            
    }

            
}

            

When you have implemented your custom aggregation service, you can register it like shown below.

            
var provider = new ServiceCollection()

            
    .AddOpenAIExtensions()

            
    .WithEmbeddingModel((opt, sp) =>

            
    {

            
    })

            
    .WithEmbeddingAggregationService<MyCustomAggregationService>()

            
    .Services

            
    .BuildServiceProvider();

            

Wrapping Up: Smarter Embeddings with Less Effort

Working with long input text and vector embedding models doesn’t have to be complicated. Denomica.OpenAI.Extensions provides a clean and extensible way to handle both text chunking and embedding aggregation – without writing boilerplate code or reinventing the wheel. Whether you’re using the default weighted average logic or plugging in your own services, the library is designed to fit naturally into your AI-driven .NET applications. Give it a try via NuGet , and feel free to explore, extend, or contribute .

Vector Embedding Model Comparison with Multilingual Text

July 8, 2025

Lately, I’ve been spending quite a lot of time working with vector embeddings and Cosmos DB Vector Search . Since I live in Finland, I work a lot with information in another language than English. That’s why I set out to do this vector embedding model comparison using a handful of the vector embedding models available in Azure AI Foundry.

Comparison Focus

As I wrote in a previous article, embedding models can be language agnostic . In this comparison, I also wanted to get some kind of understanding of how language agnostic they can. I also wanted to see whether there is any difference between various embedding models.

Another area I wanted to focus on was to see how good different embedding models are to capture the semantic context of an input instead of literally capturing the meaning. What I mean by this is that I wanted to check how similar input is when it’s written differently, but essentially means the same thing. So for instance “the weather is nice” should be quite similar to “enjoyable weather” or “the sun is shining from a clear blue sky”.

Vector Embedding Model List

In this comparison, I used the following embedding models available in Azure AI Foundry .

• embed-v-4-0
• Cohere-embed-v3-english
• Cohere-embed-v3-multilingual
• text-embedding-3-large
• text-embedding-3-small
• text-embedding-ada-002

Test Rig for Vector Embedding Model Comparison

I created a simple console application for running my vector embedding model comparison. It takes two strings, creates a vector for both strings using the embedding models I included in the comparison, and then calculates a similarity score for the produced vectors. The similarity score is calculated using the following function that calculates the similarity using cosine similarity.

            
static double CosineSimilarity(float[] v1, float[] v2)

            
{

            
    if (v1.Length != v2.Length)

            
        throw new ArgumentException("Vectors must be of same length.");

            

            
    double dot = 0.0, mag1 = 0.0, mag2 = 0.0;

            
    for (int i = 0; i < v1.Length; i++)

            
    {

            
        dot += v1[i] * v2[i];

            
        mag1 += v1[i] * v1[i];

            
        mag2 += v2[i] * v2[i];

            
    }

            
    if (mag1 == 0 || mag2 == 0)

            
        return 0; // Avoid division by zero

            

            
    return dot / (Math.Sqrt(mag1) * Math.Sqrt(mag2));

            
}

            

Vector Embedding Model Comparison

So let’s start testing. I’ve added each test case as a sub chapter. Each test case defines the two texts used, and a table representing the similarity produced by the embedding models included in this comparison.

The similarity score using cosine similarity metrics can vary between -1 (least similar) to +1 (most similar). In the tables, similarity score is rounded to 2 decimals.

Test #1

Let’s start with a very simple test with two short, very similar texts.

1. Apples are red. Bananas are yellow.
2. Apples have a red color. Bananas are colored yellow.

| Embedding Model | Similarity Score | | ---------------------------- | ---------------- | | embed-v-4-0 | 0.86 | | Cohere-embed-v3-english | 0.97 | | Cohere-embed-v3-multilingual | 0.97 | | text-embedding-3-large | 0.87 | | text-embedding-3-small | 0.91 | | text-embedding-ada-002 | 0.97 |

Test #2

Now let’s use the same text from the previous test, but translate the other text into Finnish, as precisely as possible.

1. Apples are red. Bananas are yellow.
2. Omenat ovat punaisia. Banaanit ovat keltaisia.

| Embedding Model | Similarity Score | | ---------------------------- | ---------------- | | embed-v-4-0 | 0.53 | | Cohere-embed-v3-english | 0.37 | | Cohere-embed-v3-multilingual | 0.66 | | text-embedding-3-large | 0.57 | | text-embedding-3-small | 0.49 | | text-embedding-ada-002 | 0.84 |

Test #3

Let’s move on to describing the sun setting.

1. The sun sets beautifully over the calm ocean.
2. The sun descends gracefully above the tranquil sea.

| Embedding Model | Similarity Score | | ---------------------------- | ---------------- | | embed-v-4-0 | 0.80 | | Cohere-embed-v3-english | 0.82 | | Cohere-embed-v3-multilingual | 0.92 | | text-embedding-3-large | 0.76 | | text-embedding-3-small | 0.78 | | text-embedding-ada-002 | 0.96 |

Test #4

Now let’s do the same as in the previous test, but translate the first language into Swedish.

1. The sun sets beautifully over the calm ocean.
2. Solen går vackert ner över det lugna havet.

| Embedding Model | Similarity Score | | ---------------------------- | ---------------- | | embed-v-4-0 | 0.68 | | Cohere-embed-v3-english | 0.26 | | Cohere-embed-v3-multilingual | 0.81 | | text-embedding-3-large | 0.63 | | text-embedding-3-small | 0.61 | | text-embedding-ada-002 | 0.87 |

Test #5

Now we move on to a bit longer texts. First, two texts in English written in different ways, still keeping the semantic meaning intact.

1. In the south-western Finnish archipelago, a summer sunset paints the sky in hues of gold, pink, and deep orange, reflecting over the calm sea. The warm evening air carries the scent of saltwater and blooming wildflowers, while gentle waves lap against the rocky shoreline. As the sun dips below the horizon, the archipelago’s countless small islands cast long, soft shadows over the tranquil waters, creating a breathtakingly serene scene.
2. In the south-western archipelago of Finland, a summer evening sky is illuminated with shades of gold, pink, and rich orange, mirrored on the still surface of the sea. The mild night air is filled with the aroma of sea spray and blossoming wildflowers, as soft waves brush against the rocky coast. When the sun sinks beneath the horizon, the many tiny islands of the archipelago stretch their gentle shadows across the peaceful waters, forming an extraordinarily calm and beautiful landscape.

| Embedding Model | Similarity Score | | ---------------------------- | ---------------- | | embed-v-4-0 | 0.86 | | Cohere-embed-v3-english | 0.94 | | Cohere-embed-v3-multilingual | 0.94 | | text-embedding-3-large | 0.95 | | text-embedding-3-small | 0.92 | | text-embedding-ada-002 | 0.98 |

Test #6

Now we take the text from the previous test and translate it to Finnish.

1. In the south-western Finnish archipelago, a summer sunset paints the sky in hues of gold, pink, and deep orange, reflecting over the calm sea. The warm evening air carries the scent of saltwater and blooming wildflowers, while gentle waves lap against the rocky shoreline. As the sun dips below the horizon, the archipelago’s countless small islands cast long, soft shadows over the tranquil waters, creating a breathtakingly serene scene.
2. Kesäinen auringonlasku Lounais-Suomen saaristossa maalaa taivaan kultaisiin, pinkkeihin ja syvänoransseihin sävyihin, jotka heijastuvat tyyneen mereen. Lämmin iltailma kantaa mukanaan suolaveden ja kukkivien luonnonkukkien tuoksua, kun lempeät aallot huuhtovat kivikkoista rantaa. Auringon vajotessa horisontin taakse lukuisat pikkusaaret heittävät pitkiä, pehmeitä varjoja rauhallisen veden ylle, luoden henkeäsalpaavan seesteisen maiseman.

| Embedding Model | Similarity Score | | ---------------------------- | ---------------- | | embed-v-4-0 | 0.34 | | Cohere-embed-v3-english | 0.41 | | Cohere-embed-v3-multilingual | 0.74 | | text-embedding-3-large | 0.74 | | text-embedding-3-small | 0.66 | | text-embedding-ada-002 | 0.91 |

Test #7

Let’s twist up things a little more and take the Finnish text from the previous test and translate that into Swedish.

1. Kesäinen auringonlasku Lounais-Suomen saaristossa maalaa taivaan kultaisiin, pinkkeihin ja syvänoransseihin sävyihin, jotka heijastuvat tyyneen mereen. Lämmin iltailma kantaa mukanaan suolaveden ja kukkivien luonnonkukkien tuoksua, kun lempeät aallot huuhtovat kivikkoista rantaa. Auringon vajotessa horisontin taakse lukuisat pikkusaaret heittävät pitkiä, pehmeitä varjoja rauhallisen veden ylle, luoden henkeäsalpaavan seesteisen maiseman.
2. En somrig solnedgång i sydvästra Finlands skärgård målar himlen i gyllene, rosa och djupt orange nyanser som speglas i det stilla havet. Den varma kvällsluften bär med sig doften av saltvatten och blommande vilda blommor, medan mjuka vågor sköljer mot den steniga stranden. När solen sjunker bakom horisonten kastar de otaliga små öarna långa, mjuka skuggor över det lugna vattnet och skapar ett andlöst fridfullt landskap.

| Embedding Model | Similarity Score | | ---------------------------- | ---------------- | | embed-v-4-0 | 0.41 | | Cohere-embed-v3-english | 0.49 | | Cohere-embed-v3-multilingual | 0.75 | | text-embedding-3-large | 0.83 | | text-embedding-3-small | 0.66 | | text-embedding-ada-002 | 0.90 |

Test #8

Now, let’s twist this up even further. We create two texts in different language, and try to make them as different as possible. The first text is the same text we’ve used in the previous tests. The second text is a product description for the Kalevala Kosmos Pedant in bronze in Finnish.

1. In the south-western Finnish archipelago, a summer sunset paints the sky in hues of gold, pink, and deep orange, reflecting over the calm sea. The warm evening air carries the scent of saltwater and blooming wildflowers, while gentle waves lap against the rocky shoreline. As the sun dips below the horizon, the archipelago’s countless small islands cast long, soft shadows over the tranquil waters, creating a breathtakingly serene scene.
2. Kosmoksen kirkas pronssi hehkuu lämpimissä sävyissä. Kullanhohtoisen pronssin ja mustan tai turkoosin korukiven yhdistelmä luo näyttäviin Kosmos-koruihin jännitettä ja dramatiikkaa. Papuketjussa säädettävä pituus 45/42 cm. Papukaijalukko. Jos ketju on sinulle liian lyhyt, saat siihen kätevästi lisää mittaa erikseen myytävällä jatkopalalla. Jatkopala kiinnitetään siinä olevalla papukaijalukolla korun ketjuun jatkeeksi. Jatkopalan pituus 5 cm.

| Embedding Model | Similarity Score | | ---------------------------- | ---------------- | | embed-v-4-0 | 0.21 | | Cohere-embed-v3-english | 0.35 | | Cohere-embed-v3-multilingual | 0.33 | | text-embedding-3-large | 0.17 | | text-embedding-3-small | 0.19 | | text-embedding-ada-002 | 0.79 |

Test #9

Let’s do one final test. Use two texts in English and try to make them as different as possible.

1. The impressive Kosmos pendant is embellished with a gleaming black onyx or a tranquil turquoise. Made of bright bronze, the pendant glows like gold and is a true eye-catcher. Adjustable length 42/45 cm. Lobster clasp. If the chain is too short for you, you can easily add length to it with a 5 cm extension piece sold separately.
2. To be, or not to be, that is the question: Whether ’tis nobler in the mind to suffer the slings and arrows of outrageous fortune, or to take arms against a sea of troubles and by opposing end them.

| Embedding Model | Similarity Score | | ---------------------------- | ---------------- | | embed-v-4-0 | 0.19 | | Cohere-embed-v3-english | 0.10 | | Cohere-embed-v3-multilingual | 0.27 | | text-embedding-3-large | 0.07 | | text-embedding-3-small | 0.07 | | text-embedding-ada-002 | 0.71 |

Summary

So what did I get out of this vector embedding model comparison? At first I was surprised how good the text-embedding-ada-002 was performing to find similarity between different texts. However, in the last two tests, where the two texts are very different, that model still thought the texts were quite similar. Because of this, I would not use the text-embedding-ada-002 model for anything.

The second observation is that the text-embedding-3-large model performs as well, or even better than the Cohere-embed-v3-multilingual model, except for with very short input. However, when comparing vectors for short text in different languages, the Cohere-embed-v3-multilingual model is not performing significantly better than for instance text-embedding-3-large , or even the text-embedding-3-small model.

So which one should you pick for your purpose? As with many architectural decisions – It depends, and I would say it depends on whether your inputs (the texts that you vectorize) are all in the same language, or if you need to be able to find similarities (or differences) across different languages.

If your inputs are all in the same language, the text-embedding-3-large seems to perform quite well. The text-embedding-3-small works also well, and is a much cheaper option .

But, if you are processing inputs in different languages, and processing texts that are anything than short sentences, I would go with either the text-embedding-3-large or Cohere-embed-v3-multilingual model. Since the cost for the Cohere-embed-v3-multilingual is $0.0001 / 1000 tokens or roughly 0.000093 EUR / 1000 tokens, it is about the same as text-embedding-3-large , which is around 0.000112 EUR / 1000 tokens.

To make those figures a bit more tangible, the cost for 10 000 000 tokens for each of these two models is:

• text-embedding-3-large : 1.12 EUR / 10 000 000 tokens
• Cohere-embed-v3-multilingual : 0.93 EUR / 10 000 000 tokens

Because the text-embedding-3-large embedding model is better at recognizing differences and on par with the Cohere-embed-v3-multilingual model, I would go with the text-embedding-3-large model in multi-lingual scenarios, even if that model is just a tad more expensive. The difference is still quite negligible.

Vector Embeddings For Long Documents

March 31, 2025

How do you create vector embeddings for long documents or long texts? This might be a question you find asking yourself when working with vector embeddings. This article is a follow-up to my previous article where I showed you how you can create vector embeddings with Azure AI Foundry and store them in Cosmos DB.

Problem Description

Currently, all embedding models in Azure AI Foundry have a limit on how long the input text can be. Limits may vary from model to model, but there is a limit on each embedding model. You can read more about the details in my previous article . The main point is – If your input text is longer than the limit, you need to chunk up your input text, and generate the vectors for each chunk separately, as suggested on Microsoft Learn .

This will result in your input text being represented by more than one vector embedding. This might be an acceptable solution in some cases. However, I think that in most cases you would also want to have a vector embedding that represents the entire input text, regardless of how long the input text is.

Combining Multiple Vectors Into One

One good solution is to take each chunk of input text and create a vector embedding out of the text. Then you would combine each chunk vector into a single vector that represents the entire input text. Now how would you do that then?

Remember that the length of a vector generated by an embedding model is constant. For instance, the text-embedding-3-small embedding model generates a vector with 1536 dimensions, by default. You can then just take the average of each dimension in each of your chunk vector. This would create quite a good result.

However, to make this result even better, you could create the resulting vector as a weighted average. When you use embedding models in Azure AI Foundry, in addition to the embedding vector, you also get a score that indicates how many tokens were consumed to produce that vector embedding. This consumption score is a good option to be used as the weight. The more tokens that you consume to generate an embedding vector, the longer and more complex the input text is. And because of that, it should also have a bigger influence on the resulting average. Let me explain using an example.

Let’s take the following two short and simple vector embedding responses.

            
// Vector Embedding #1

            

            
{

            
    "data": [

            
        "embedding": [1,2,1]

            
    ],

            
    "usage": {

            
        "total_tokens": 10

            
    }

            
}

            

            
// Vector Embedding #2

            

            
{

            
    "data": [

            
        "embedding": [1,2,5]

            
    ],

            
    "usage": {

            
        "total_tokens": 2

            
    }

            
}

            

These two vector embedding results are overly simplified for a better overview. Each vector has 3 dimensions. The resulting vector would then also have 3 dimensions.

If the dimension value in the first vector is D1 , the dimension value in the second vector is D1 , the number of consumed tokens for the first vector is T1 and the consumed tokens for the second vector is T2 , then each dimension value for the resulting vector embedding ( Tr ) would be calculated as below.

            
Tr = ((D1 * T1) + (D2 * T2)) / (T1 + T2)

            

This would result in the following dimension values using the sample vectors from above.

1. ((1 10) + (1 2)) / (10 + 2) = 1
2. ((2 10) + (2 2)) / (10 + 2) = 2
3. ((1 10) + (5 2)) / (10 + 2) = 1.66

So the resulting vector using weighted average is [1,2,1.66] . A pure average operation without weights would have produced a vector [1,2,3] .

Conclusion

Using a weighted average is better that a pure average, since your chunks can vary is both size and complexity. However, this solves only half of the problem. You still have to figure out *how * to produce your chunks from your long input text.

I am currently working on a library that will help you with both chunking and calculating vector embeddings from chunked text. I will publish a link to that library when it’s ready for publishing, so stay tuned.

Cosmos DB Vector Search \u2013 An Introduction

February 22, 2025

Applications powered by Generative AI are becoming more and more popular. Often these applications employ some kind of RAG (Retrieval-Augmented Generation) solution patterns. For RAG powered applications, the Cosmos DB Vector Search feature can be very useful. In this article I’ll describe this feature in more detail. This will give you better information to base your decisions on when deciding whether you could leverage this in your applications.

You might also want to have a look at another article where I compare Cosmos DB vector search with traditional indexing .

Understanding Vector Embeddings

A vector embedding is basically an array of floating-point numbers. What is also characteristic for embeddings is that they are fixed-sized. It does not matter how long or complex the input is. The vector embedding generated by one model always has the same number of dimensions. However, some models allow you to specify the number of dimensions you want in the vector embedding.

But what makes vector embeddings so useful is that they encapsulate the semantic context of the input. The closer a vector is to another vector, the more similar the inputs represented by the vectors are. You can think of a vector as a path. If your input talks about bananas, the resulting vector or “path” passes close to the “area” where fruits are discussed. If your input talks about cars, then the path goes by the “area” where vehicles are discussed. This analogy helped me to get my mind around the concept of vector embeddings. This document from Microsoft Learn about Vector Embeddings in Cosmos DB can also give you a better idea of how vector embeddings are designed to work.

You use Cosmos DB Vector Search to find content similar to something else. To find similar content you first generate a vector (“query vector”) for the data you want to find similar content to. Then you search for content with vectors that are closest to your query vector. You must generate the query vector in the same way as you generated the vectors for your content. This includes also using the same embedding model. If you decide to switch model, you need to regenerate the vectors that you have stored.

Vector Embeddings Can Be Language Agnostic

Since embedding models capture the semantic context of the input rather than the actual content, they can also be language agnostic. However, this is not always the case. Some models might be better on capturing semantics regardless of the language than others. If you have an embedding model that is truly language agnostic, the vectors they produce for input with the same meaning but in different languages, should be very similar. This can be helpful if your content is in another language that you use when creating your query vectors. If this is an important requirement for you, you need to do your due diligence and make sure that you pick an embedding model that can properly handle different languages.

Setting up Cosmos DB Vector Search

The first thing you have to do to turn on Cosmos DB Vector Search is to enable that feature on your Cosmos DB account. There are two steps to enable Cosmos DB Vector Search:

1. Turn on the feature for your Cosmos DB Account
2. Create a container with a vector policy

Note! Once you have turned that feature on, you cannot turn it off again. It is a one-way street, so remember this before you go on turning on this feature on all your Cosmos DB accounts.

You can turn this feature on in the Azure portal. Navigate to your Cosmos DB account and select Settings/Features from the menu. Then turn on the Vector Search for NoSQL API feature.

image

Next you need to create a container with a vector policy.

Note! Currently, vector policies in Cosmos DB are immutable, meaning that you can’t change the policy after the container has been created. If you need to change it, you must create a new container with a new vector policy, and migrate your data to the new container.

You define the vector policy on the same dialog where you create your container.

image-1

• Path : This is the path to the attribute on your JSON documents that contains the vector.
• Data type : The data type for the values in your vector. This value needs to match the data type your embedding model supports. Typically, embedding models create vectors containing floating-point numbers.
• Distance function : The function to use for calculating vector distance. A cosine function returns a value between -1 and +1 representing the similarity. A score of -1 is least similar and +1 is most similar.
• Dimensions : The number of dimensions of your vectors, i.e. items in the floating-point number array. You need to check the number of dimensions supported by the embedding model you plan to use.
• Index type : The index type to use. Read more about index types for Cosmos DB . With the index type, you can potentially decrease the the amount of Request Units (RUs) your vector queries consume, so be sure to check this out.

Generating Vectors with Embedding Models in Azure AI Foundry

There are many ways to generate vector embeddings. However, in this article I focus on generating them with the help of models deployed in Azure AI Foundry . You can use different kinds of SDKs to communicate with model deployments in Azure AI Foundry. I will not use any of those, but use simple REST calls to demonstrate how to communicate. I believe that this will give you the best understanding of how things actually work. It will then make it much easier for you to use an SDK or write your own, when you know how stuff works under the hood.

Provisioning the Required Azure Resources

To generate a vector, you need to provision an Azure OpenAI resource.

image-2

Then you need to deploy a model that is designed to be used for embeddings. There are several embedding models available. The text-embedding-3-small and text-embedding-3-large are probably the most recent models currently, at the time of writing (late Feb 2025).

I will use the text-embedding-3-small model in this example. It is much cheaper than its larger counterpart. However, you can pick any model that is capable of creating vector embeddings from text. Note that there are also embedding models that can create vector embeddings from images. Those models are out of the scope of this article. I’ll have to come back to those in a later article.

Creating the HTTP Requests

After you have deployed your embedding model, for instance the text-embedding-3-small , select the deployed model to open the Details page for the deployment.

image-4

On the Details page, copy the Target URI and Key to use when sending requests. All requests to this endpoint are POST requests with the key added to the api-key request header. In Postman , you can create one collection and define the authorization settings on the collection level. This way, all requests in that collection will inherit the same settings. The Postman settings are below.

image-5

The request body looks like this.

            
{

            
    "input": "Your text to generate the vector embedding for."

            
}

            

You can also specify specify multiple input strings by setting the input attribute to an array of strings, like this:

            
{

            
    "input": [

            
        "This is your first string.",

            
        "The second string to generate vector embeddings for."

            
    ]

            
}

            

When you specify multiple input strings, you will also get the same amount of vector embeddings in the response. With embedding models like text-embedding-3-small and text-embedding-3-large , you can also specify the number of dimensions you want in the resulting vector embedding. The number of dimensions are specified in the request body as shown below.

            
{

            
    "input": "My name is Bond. James Bond.",

            
    "dimensions": 1024

            
}

            

For the text-embedding-3-small model, the minimum number of dimensions is 1 , and the maximum number is 1536 . For text-embedding-3-large , the minimum number of dimensions is also 1 , but the maximum number is 3072 . The more dimensions you have, the better you can capture different nuances in the input text. On the other hand, larger vectors take up more storage space in Cosmos DB and consume more Request Units when you query for data.

Note! Currently, there is a limitation for how long the input can be. Unfortunately there is no absolute limit that you could easily check before you send the request. Instead, the limit is expressed in tokens . The maximum input tokens for text-embedding-3-small and text-embedding-3-large are 8191 tokens. How many tokens that are consumed by a given text depends on many factors, such as language, text complexity etc. In general, a fair estimate for standard English text is that around 4 characters consume 1 token . This means that in theory, you should be able to generate vector embeddings as described above for a text containing 32 764 characters. Some text can be longer and some text can be shorter.

There are various patterns you can employ to generate vectors for larger text. I’ve written about the weighted average pattern in a previous article Vector Embeddings for Long Documents .

Storing the Generated Vector for Cosmos DB Vector Search

When sending the request as described above, you will get a response that looks like this.

            
 {

            
    "object": "list",

            
    "data": [

            
        {

            
            "object": "embedding",

            
            "index": 0,

            
            "embedding": [

            
                0.006165823,

            
                0.013940725,

            
                -0.066804506,

            
                0.015688516,

            
                // ...

            
                0.056068067,

            
                0.036370724,

            
                -0.0026667705,

            
                -0.008225721

            
            ]

            
        }

            
    ],

            
    "model": "text-embedding-3-small",

            
    "usage": {

            
        "prompt_tokens": 8,

            
        "total_tokens": 8

            
    }

            
}

            

This response message is pretty self-explanatory. If you created your Cosmos DB container and vector policy as above, then you would probably store this vector in your container using a JSON document similar to the following.

            
{

            
    "id": "5b39d118-65b6-46f4-a402-95c54b9e2648",

            
    "partition": "partition-1",

            
    "content": {

            
        "text": "My name is Bond. James Bond."

            
    },

            
    "embedding": {

            
        "vector": [

            
            0.006165823,

            
            0.013940725,

            
            -0.066804506,

            
            0.015688516,

            
            // ...

            
            0.056068067,

            
            0.036370724,

            
            -0.0026667705,

            
            -0.008225721

            
        ],

            
        "totalTokens": 8

            
    }

            
}

            

Since this is a completely normal JSON document stored in a completely normal Cosmos DB container, you can of course add whatever data you think you need to store in this document. This can be anything you need to be able to effectively query the data later on.

Querying Data in Cosmos DB Vector Search

When querying your data using Cosmos DB Vector Search, you pretty much build your SQL query just as you normally would, with a few distinct differences.

1. You use the built-in VectorDistance function to order your results
2. You must always specify SELECT TOP n to limit the number of items returned in the result

The VectorDistance function compares a given vector to the vector of each document matching the filters of the query. The result is then ordered so that the documents with the vectors closest to the vector specified in the query are listed first. The sample SQL query below uses the @queryVector parameter as placeholder for the vector.

            
SELECT TOP 5 c.id,c.partition,c.content, VectorDistance(c.embedding.vector, @queryVector) AS distance

            
FROM c

            
WHERE c.distance >= 0.8

            
order by VectorDistance(c.embedding.vector, @queryVector)

            

This query would return 5 JSON documents where the embedding vector is closest to your query vector. This means that the content in the resulting JSON documents is semantically most similar to the text that you used to generate the query vector.

The WHERE clause will further filter out the result to include only those documents that are actually similar to the query vector. This is to make sure that the result actually contains content similar to the query and not just something that is most similar even though not even close to what you are looking for.

Imagine that you have a container only containing documents describing various car models. Now, if you would query the container for recipes on deserts with bananas, you would get 5 documents describing car models. They are not similar at all to what you were looking for, but are the closest ones when there are no desert recipes in your container.

Filtering on Similarity

There is no exact description for what the values returned by the VectorDistance function actually mean, but you can use the following for some kind of basis for your decisions. If you are using the Cosine function as your distance function, the VectorDistance function returns a floating-point number between -1 and +1. -1 means no similarity at all, and +1 means very similar, if not even identical.

• +0.80 to +1 : Very similar. These results are highly relevant and closely match your query.
• +0.50 to +0.79 : Moderately similar. These results are somewhat relevant but may not be exact matches.
• 0 to +0.49 : Low similarity. These results are not very relevant to your query.
• Below 0 : Not similar. These results are quite dissimilar to your query.

Remember that what is considered “similar enough” can vary depending on your specific use case and context. Setting the similarity filter to +0.80 or above ensures that the result contains only highly relevant documents. I would suggest that you would run some tests with your content vectors and match them to expected query vectors to get the similarity filter to best suit your needs.

Practical Examples of Using Cosmos DB Vector Search

So what would you use the Cosmos DB Vector Search for? Why bother? Why not just use the vector indexes provided in Azure AI Search or Azure AI Foundry? Well, one thing for sure is that you have more control over what content is included in your query results. You also have control over how you generate vector embeddings for your content. If you have long documents, you could also split the documents into smaller parts like paragraphs or chapters, and generate vector embeddings for each part separately.

And you don’t have to settle for just searching for content similar to your query vector. You can add whatever filters you need to find the right content. Remember, that you are executing normal Cosmos DB SQL queries. In the chapters below I outline a few practical examples where you can leverage Cosmos DB Vector Search, some of which I have been working on, or will be working on myself.

Customer Knowledge Base

Let’s say you have a customer extranet that your customers log in to. On this extranet you have a lot of guidance and instructions related to the services that you offer your customers. But not all of your customers subscribe to the same services. Some of the instructions you publish are irrelevant to many of your customers. You might even have customer specific instructions that are relevant only to one customer and its representants.

With Cosmos DB Vector Search you could easily create vector embeddings for your instructions as shown in this article. You would then store these vectors in your Cosmos DB container along with information about what or which services each document is related to, or it it is related to just one particular customer. Then when your customers want to find something, you create a query vector from the customer’s search prompt and use that to find the most relevant instructions. You would also add more filters to include only instructions that are relevant to the customer and the services it subscribes to.

Suggest Similar Products or Content

Imagine you have an online store with a bunch of products. Your product information along with the product description is stored in a Cosmos DB container. You would also store the vector embedding for the product description with the rest of the product information.

Now when a visitor views a product, you could take the vector embedding for that product and find other products in your Cosmos DB container that are similar to the viewed product. The product being viewed would of course be the most similar, so you would need to filter out that particular product from the query results. Since you are running a standard Cosmos DB SQL query, that would be quite simple.

This same approach can be useful also for suggesting any type of content that is similar to for instance what is currently being viewed in an application. Take the previous example of a Customer Knowledge Base. When you display one instruction document, you could also offer other similar instructions, again filtering on the services the logged in customer is subscribed to.

Process Survey Responses

If you are in the business of doing surveys, you might find yourself in a situation where you are overwhelmed with the amount of responses. You might struggle with properly processing each response separately.

In some cases, you might be able to process responses in groups. To find these groups you might want to try to find similar responses, and then process the most similar responses in batches.

Document Classification

Some times you might have systems that store a lot of documents, and you need to categorize and classify these. Then you could pick one uncategorized document and categorize it manually. With the help of Cosmos DB Vector Search you find similar documents with the document that you categorized manually, and then categorize the most similar documents the same way you categorized the first document manually.

Multi-lingual Services

Since vector embeddings can be language agnostic , you could offer multi-language RAG solutions, without having to publish content in multiple languages. You could allow your users to give their prompts in whatever language they want, and create a vector embedding (query vector) from that. Then query the most similar documents using the query vector, and use the resulting documents as input to a chat completion model that would use the given documents to provide a response to the original prompt, and in the same language as that prompt. Of course, you would have to make sure that the embedding model you choose properly handles and supports multiple languages.

If you would like to display the documents returned by the similarity query, you could use a translation service to translate the original document into the language that the original user prompt was written in. You could also try to use a chat completion model to do the translation. Optionally, you could store that translation for future use so that you would not have to use a translation service every time.

How Much Does It Cost

So what does it cost to generate vector embeddings? That depends on the embedding model you use. I will use the text-embedding-3-small and text-embedding-3-large embedding models as example.

Remember that I talked about tokens above. The pricing for generating vector embeddings is also based on how many tokens you consume. The prices below (at the time of writing on late Feb 2025) are for 1000 tokens.

• text-embedding-3-small : 0.000020 EUR/1000 tokens
• text-embedding-3-large : 0.000125 EUR/1000 tokens

If we take the maximum number of tokens both of these embedding models support, 8191 tokens, and estimate that to a text of the length of 32 764 characters, it would incur the following costs with both of these models.

• text-embedding-3-small : 0.000164 EUR -> 0.0164 cents
• text-embedding-3-large : 0.00102 EUR -> 0.102 cents

Both of these costs are clearly peanuts, so we need to add more volume to the sample. Let’s assume that you have 10 000 documents that are all the maximum size supported by the embedding models, the cost for generating vector embeddings for all of those documents with each of the models would then be.

• text-embedding-3-small : 1,64 EUR
• text-embedding-3-large : 10,24 EUR

Still a pretty manageable cost, even for personal use I would say.

Conclusion and Further Reading

I hope that this article has given you at least some new information about what Cosmos DB Vector Search is, and what you might use it for. I believe that it is good to have options to choose from when designing solutions to tackle various problems. Of course, the more options you have, the more likely you are also to pick an option that is perhaps not the optimal for a particular case. The more you know and understand about the options you have, the better decisions you can make.

The following links provide you with further reading to get more information for even better decisions.

• My other Cosmos DB articles
• What is a Vector Database
• Vector Search in Azure Cosmos DB for NoSQL
• Vector indexes in Cosmos DB
• VectorDistance function
• Vector Embeddings in Azure Cosmos DB
• Introducing Text and Code Embeddings

Blazor Apps With Mermaid Diagrams Using Blazorade Mermaid

February 28, 2024

Blazor and Mermaid are two technologies that merge into one with the help of Blazorade Mermaid . It is the latest member to the Blazorade family. This article shows you how easy it is to add Mermaid diagrams to your Blazor applications by using Blazorade Mermaid.

Mermaid in Short

Mermaid is a JavaScript based diagramming and charting tool that renders diagrams in any web application. It takes simple formatted text inspired by Markdown , and turns that into visual elements.

Since Mermaid is essentially JavaScript, it might be a bit tricky to utilize it in your Blazor applications. Even if JavaScript interop is pretty easy to manage in Blazor, you still have to know how JavaScript works to do it successfully.

Blazor + Mermaid = Blazorade Mermaid

image-1-300x204

One of the key principles in Blazorade is to make it as easy as possible to create Blazor applications and use popular libraries like Mermaid. With libraries or frameworks that expose functionality through JavaScript this means that Blazorade will take care of that communication. Your application does not need to figure out how to do that.

Again, I’m not saying that calling into JavaScript from a Blazor app is hard. On the contrary! Blazor makes it relatively easy. But still, it is way easier to call into and interact with a component that looks and works just like any other Blazor component.

This is what Blazorade Mermaid does for your application. You just add the Blazorade Mermaid Nuget package to your application and add the <MermaidDiagram /> component wherever you want to have a diagram. You don’t even have to worry about how and where to reference the Mermaid JavaScript library. That’s all taken care of by Blazorade Mermaid.

And if you want to change or update the diagram, just change the MermaidDiagram.Definition parameter, and it will automatically update for you. Can’t be much easier than that, can it?

Getting Started With Blazorade Mermaid

There are three steps to start using Blazorade Mermaid in your Blazor application.

• Add a reference to the Blazorade Mermaid Nuget package.

• Add @using Blazorade.Mermaid.Components to your _Imports.razor file.

• Add the <MermaidDiagram /> component to your page or component.

Again, you don’t even have to add any JavaScript references to your page layout. That’s all taken care of by Blazorade Mermaid.

Sample Blazor With Mermaid Diagrams

So it’s time to have a look at an example that demonstrates how to Mermaid diagrams to your Blazor application.

            
<div>

            
    <MermaidDiagram Definition="@this.diagramDef" />

            
</div>

            

            
@code {

            
    string diagramDef = string.Empty;

            
}

            

Whenever you update the diagramDef variable in your code, that will immediately update the rendered diagram too.

Now let’s take that a bit further and switch between two different diagrams using two buttons.

            
<button @onclick="() => this.diagramDef = def1">Flowchart</button>

            
| <button @onclick="() => this.diagramDef = def2">Mindmap</button>

            

            
<MermaidDiagram Definition="@this.diagramDef" />

            

            
@code {

            
    string diagramDef = def1;

            
    

            
    const string def1 = @"

            
flowchart LR

            
A --> B

            
B --> C

            
C --> A

            
";

            
    

            
    const string def2 = @"

            
mindmap

            
Responsibilities

            
  HR

            
    Salaries

            
    Healthcare

            
  IT

            
    Workstations

            
    Phones

            
  Sales

            
    Sell, sell, sell!

            
  Operations

            
    Operate

            
  Marketing

            
    Branding

            
    Website

            
";

            
}

            

In this sample, whenever you click either the *Flowchart or Mindmap * buttons, the diagram will change accordingly.

You can find more samples on the Blazorade Mermaid wiki.

Future of Blazorade Mermaid

At the time of writing this article (Feb 2024), the first stable version of Blazorade Mermaid has just been released. The first versions of Blazorade Mermaid focus on viewing diagrams and making that as easy as possible. However, there are a few other areas that Blazorade Mermaid will focus on in coming versions.

Support for Themes

It is completely possible to define themes and customize them in the diagram definition that is rendered by Mermaid. But sometimes you might want to separate that from the diagram definition. You might even want to prevent themes and customization completely in the diagram definitions, and override that with your own.

You can track this feature on the backlog .

Diagram Interaction

Certain types of diagrams have built-in support for some level of interaction. For instance a flowchart allows you to define nodes as links. You can also define JavaScript callbacks directly in the diagram definition.

However, this is not the optimal way of handling things. You are effectively blending content with application logic. A better option is to allow the application to handle clicks, and then make decisions based on the node that was clicked.

You can track this feature on the backlog .

Support for .NET MAUI

Originally, Blazorade started out as a browser-only kind of thing. That was before .NET MAUI and its support for using Blazor components through .NET MAUI Blazor Hybrid applications .

Having MAUI support in Blazorade libraries would allow Blazorade libraries to be used in a wider range of applications. I think it would be cool to use Blazorade libraries for instance in Android TV applications.

So, I decided that Blazorade libraries should, as far as possible, support any platform that supports Blazor , including desktop and mobile platforms.

You can track this feature on the backlog .

Contributing to Blazorade Mermaid

So as you can see, there is still a bit left to do before Blazorade Mermaid is “perfect” ;). You are welcome to join that work. You can let me know by adding a comment to this article, or by starting a discussion on the discussion board for Blazorade Mermaid.

And if you feel like just using Blazorade Mermaid in your application, that is of course completely fine too. I hope that Blazorade Mermaid will make your application development a bit easier.

Understanding TOTP Codes: A Short Guide to Securing Your Accounts

January 22, 2024

In the world of online security, *TOTP codes ( T ime-based O ne- T ime P *assword) are like your account’s secret superhero. They add an extra layer of protection to make sure only you get into your accounts. Let’s break down what TOTP codes are, what they’re used for, and how they’re cooked up without diving into fancy tech talk.

What Are TOTP Codes?

Imagine TOTP codes as digital bodyguards for your online accounts. They create a special, ever-changing password that acts like a secret handshake to keep the bad guys out.

What Are They Used For?

Okay, so you’ve probably seen that extra step when logging into your email or social media – the one where it asks for a code from your authenticator app. That’s where TOTP codes step in. They’re like the bouncer at the club, making sure only the right person (you) gets in.

How Are They Cooked Up?

Now, let’s talk about how these TOTP codes are whipped up in the kitchen of online security:

1. Setting Up : When you turn on two-factor (sometimes referred to as multi-factor ) authentication (2FA/MFA) for your account, you usually connect it to an app on your phone. This app becomes your sidekick in the fight against unauthorized access.
2. Secret Key : Your account and the app share a secret key. It’s like having a special ingredient that only you and your app know about. This key kicks off the process of making your unique TOTP codes.
3. Time Magic : There’s a secret sauce called an algorithm. It’s like a recipe that involves the current time and your secret key. Your app and the online service both use this magic to cook up the TOTP code.
4. Changing Every 30 – 60 Seconds : TOTP codes don’t stick around for long – they change every 30 – 60 seconds. This is like changing the locks on your digital door regularly. It keeps things extra secure.
5. Time Sync : For this to work smoothly, your phone and the online service need to agree on the time. But don’t worry, this is usually done automatically – no need to set your digital clocks.

Conclusion

TOTP codes might sound like tech wizardry, but they’re really just your online account’s way of putting on an extra lock. They make it way harder for someone to sneak in, even if they somehow get your password. So, the next time you see that prompt for a code from your app, think of it as your account doing a secret handshake to keep your information safe. Stay safe out there!

Further Reading

If you want to read more about TOTP codes and the algorithms behind them, have a look at Time-based one-time passwords on Wikipedia.

If you want to create applications that produce TOTPs programmatically, like UI tests and browser automation systems with Playwright , add a reference to the Otp.NET assembly in your code.

How to Do MFA Login With Playwright

January 21, 2024

Last year, in 2023, I started looking more into Playwright for both testing and browser automation. I also ended up in a situation where I needed to do login to Microsoft Entra ID with an account with MFA enabled. This article describes how to write your Playwright code to successfully perform MFA login to Microsoft Entra ID .

What Is Playwright?

Before we dive in, a few words about Playwright if you are not that familiar with it yet. Playwright is a cross-platform library for automating web browsers. It allows you to write end-to-end tests, capture screenshots, generate PDFs, and perform web scraping using a consistent and user-friendly API. Playwright supports Chromium, Firefox, and WebKit browsers, and can run on Windows, Linux, and macOS.

You might have heard of Selenium . Playwright is kind of the new kid on the block in browser automation. I used to do a lot of testing and browser automation with Selenium back in the day. But Playwright has really become my favourite browser automation library. I feel the code with Playwright is much simpler and lighter than with Selenium. For instance, I don’t have to add random delays or other checks to make sure that an element is visible or clickable before I start using it in my code. Playwright does all of that for me. With Selenium, this is not the case. Your Selenium tests may still fail randomly because your timing is not right. Or then you just add unnecessary long delays or something like that. That’s all history with Playwright.

Disclaimer! It’s been several years since I’ve last worked with Selenium, so the issues I described above may be all history.

What’s the Problem With Playwright and MFA Login?

If you would have just a username and password, it would be quite simple to create automation with Playwright that would take care of login. But with MFA, login is a bit trickier. How do you get a TOTP ( T ime-based O ne- T ime P assword) from your authenticator app to your Playwright automations?

Fortunately, it is quite simple at the end of the day. The main points of the solution are:

• Configure MFA for the account so that it can be leveraged in code
• Add code to your automations that use the configuration to produce TOTPs as needed

This article walks you through all the steps you need to master MFA login in your Playwright automations.

Configure User Account

To create and configure a user account that has MFA enabled and can be used with Playwright automations, follow my Create a Shared Account With MFA in Microsoft Entra ID article that I wrote previously.

Code for Playwright Supporting MFA Login

In this chapter I’ll go through each step that is required to get your MFA login working in Playwright. You find the code examples in the chapters below in a Github repository I set up. This repository contains a fully working example of how to log in to the Microsoft 365 portal with a user account that has MFA enabled. The code checks whether MFA is required during login, and adapts accordingly. The sub chapters are associated with named blocks in the sample code.

Referenced Libraries

The application references the following Nuget packages.

• Microsoft.Playwright – The library that contains everything you need to run browser automations with Playwright.
• Otp.NET – A library that provides TOTP computing capabilities.

Initialize Objects

All Playwright automations start by creating a Playwright object using Playwright.CreateAsync() . You will also need a browser type and browser object. In the sample code I create the browser object directly by using the pw.Chromium.LaunchAsync() method. However, if you would like to run your automations on different browsers, you would create a separate browser type object, and then send that away to the implementation that does the actual automation. Playwright supports 3 browser types – *Chromium , Firefox and Webkit *.

With the browser object, you create a browser context that represents the session you are running. Using the browser context, you create a new page object that you then use in your automations.

Navigate to Application

In order to have a web application to interact with, you first navigate to the page. In the sample application we use the URL https://www.microsoft365.com/login which would redirect directly to the login page. Another option would be to navigate to https://www.microsoft365.com/ and click the Sign in button.

Define Common Selectors

There are several CSS selectors that we use across the application. These are defined at the start of the application, so that we can reuse them across the rest of the code.

Provide Username and Password

Now this is where the magic starts to happen. The first thing we do is to fill in the username in the username text box. This is done with the FillAsync() method of the page object. Then we click the *Next * button by using the ClickAsync() method.

Note! Playwright takes care of waiting for an element to be available for interaction. This means that Playwright will not perform the interaction before the element is visible, clickable, or otherwise available for interaction. This makes your code so much clearer, when you don’t have to add random delays between every line of code, just to be on the safe side. The default timeout of 30 seconds is more than enough. If an element takes longer than the assigned timeout to become available, Playwright will throw an exception.

After clicking the *Next button, the code waits for the username text box to be detached from the DOM. This needs perhaps a bit of explanation. As you know, the login to Microsoft cloud services such as Microsoft 365 is built up of multiple views. The transitions between these views use a lot of animation. In addition, the different views reuse the same CSS selectors on elements that have different meanings on different views. For instance, the Next button on the username view matches the same CSS selector as the Yes * button on the Keep me signed in view.

So, we wait for the username text box to disappear before we start processing the password.

Note that this is not the same as waiting for a fixed amount of seconds. This is waiting until something has occurred, which is completely fine.

Next step is to handle the password. This follows the same logic as handling the username.

• Fill in the password
• Click on the Next button
• Wait for the password text box to disappear from the DOM

Handle MFA Login

Since MFA is not required for every login, we need to determine whether MFA is required for the current login that we are processing. We do this by waiting for one of two elements.

1. TOTP text box
2. Keep me signed in (KMSI) checkbox

Whichever element is found first determines how we proceed in the code. If the KMSI checkbox was found first, then we know that MFA was not required and we complete the login process by clicking the *Yes * button one more time.

On the other hand, if the TOTP text box was found, then we know that we need to handle MFA login. This is where we use the MFA secret key that you preferably have stored in your password manager. Use the Otp.NET library produce a TOTP. Then, fill the TOTP text box and click the *Next * button.

Again, after clicking the *Next * button, we wait for the TOTP text box to disappear from the DOM before continuing to the next step.

Keep Me Signed In

This is the last step in the login process. Here, it actually does not make any sense to check the keep me signed in checkbox, because each browser context you start in Playwright is a clean session. It’s just like you would start your browser in the In Private/Incognito mode every time you fire up a browser with Playwright.

You can populate a browser context with storage state from a previous session including login information, but I’m skipping that here for simplicity.

So, we just click on the Yes button to complete the login.

Conclusion

So, with these steps it should be possible for you to test any application that you log in to using a Microsoft Entra ID account that has MFA enabled. The same principles apply also to accounts in Microsoft Entra External ID or Azure AD B2C. I would assume that the same works with any identity provider that supports TOTP.

Create a Shared Account With MFA in Microsoft Entra ID

January 20, 2024

There are many cases where you need to create a user account in Microsoft Entra ID (“ME-ID”) and share it with a bunch of people. Accounts created for testing purposes is a very common use for shared accounts. Usually you would just create an account with a username and password. Then you store that in a password management application and share it with your peers. My favourite password manager is definitely Bitwarden .

Note! In Microsoft 365 there are typically restrictions that apply to how shared user accounts may be used. As a rule of thumb, always create personal accounts for all your team members for normal operations. Shared accounts should only be used for development and testing purposes.

But nowadays, ME-ID has security defaults enabled by default, or has MFA enabled in other ways. That makes things more complicated. How do you share the ability to perform MFA with your team? What if you need to do MFA login in your test automation?

Luckily there is an easy way. I’ll go through the necessary steps in this article.

Create a Normal Account

You start with creating a user account like you normally would. Head over to Microsoft Entra admin center , and log in with a user account that is allowed to create user accounts. Then from the menu, select *Users / All users . Above your users list, click the New user menu item, and select Create new user *.

image

In the Create new user wizard, type in the information about the user you need.

Note! If you select the Auto-generate password option, you need to copy the password using the Copy to clipboard button next to the password field.

image-1

When you’re done, head over to the *Review + create tab. If you did not yet copy the username, you can do it here by clicking the Copy to clipboard* button.

image-2

When you have copied both the password and the username, and stored it in your password manager, for instance Bitwarden , then click the *Create * button to create the user.

First Time Login

Before you share the account with your peers, you must complete the account by logging in the first time. During the first login, you take care of the following things.

• Change the temporary password
• Configure MFA
• Optional other authentication methods

I usually log in to myaccount.microsoft.com in these kinds of situations. Remember to start your browser in the In Private mode (Edge) or Incognito (Chrome) so that you don’t mess up your regular browser profile that you are using.

Change Password

The first thing you need to do after logging is to change the temporary password.

image-3

You can use your password manager, for instance Bitwarden , to generate a unique and strong password. Remember to save your new password in your password manager. Then click *Sign in * to continue.

Configure MFA

When you completed changing the password, you need to configure multi-factor authentication settings for the account.

image-4

Even though you have 14 days to complete this step, it is a good idea to do it right away. Especially if you plan on using the account for longer than 2 weeks. You’ll have to do it anyway.

To start the MFA configuration, click on the *Next * button.

image-5

The default authenticator application is obviously Microsoft Authenticator. But, since you are planning on sharing the account with others, it is *very important that you click the I want to use a different authenticator app * link. Clicking that link will take you to the generic authenticator application configuration, as shown below.

image-6

Note! The reason why you must not select the Microsoft Authenticator option is because that will configure the MFA for the account to send challenges back to the authenticator app for you to approve. That becomes a bit tricky if you want to share the account with others. You can still use the Microsoft Authenticator application, or any other authenticator application. You just have to take the generic configuration route.

Click the *Next * button to continue with the configuration.

image-7

Click on the *Can’t scan image? * button to show the secret key that you need to save.

image-8

Copy the secret key to your clipboard, and click the *Next * button to continue. Remember to save the secret key. You will never see it again after you leave this screen.

Note! At this point, if you would like to add the account to your Microsoft Authenticator, scroll down to Add the Account to Microsoft Authenticator , and follow the steps there. Instead of entering the code manually, you can actually scan the QR code above.

image-11

In Bitwarden , you store this secret key in the *Authenticator key (TOTP) * field.

image-18

One nice thing about Bitwarden is that it can work as an authenticator app for you. When you save the account with the secret key stored in the Authenticator key field, Bitwarden will show you the TOTP ( T ime-based O ne- T ime P assword) that will work as the MFA challenge. To add the account to Microsoft Authenticator, have a look at Adding the Account to Microsoft Authenticator below.

image-9

Getting back to the MFA wizard. Here you can now try the TOTP (time-based one-time password) generated by Bitwarden. Click Next to verify that the code you entered checked out.

Optional Authentication Methods

Depending on the configuration in the ME-ID tenant you are setting up the account in, you may need to configure more authentication options. These can be for instance one-time passwords sent by text message to your mobile phone or by e-mail.

These are not required for normal use, since the username, password, and TOTP are enough for several persons to log in with the same account. Still, if they are required, you need to complete the steps in order to complete the first login for the account.

image-13

I chose the email option above. If you want to configure this step using text messages, click on the *I want to set up a different method * link. Select from the available options.

image-14

In my case, there are only two options.

image-16

When you come this far, tap your self on the shoulder. You’ve completed the initial setup for your account. When you click the Done button, you will be taken to the My Account portal.

image-17-1024x507

Remember to share the username, password and Authenticator key with your team, or whoever you were planning on sharing the account with.

Enforcing MFA Login

Even with security defaults enabled in your tenant, you may still not be required to complete an MFA challenge every time you log in. That decision is made by the security mechanisms enabled by security defaults. If you want to make sure that you are required to provide MFA verification each time you log in, you can do so by logging in to the Multifactor Verification page.

image-19

Select the user account you want to configure, and select *Enable / Disable / Enforce *.

Adding the Account to Microsoft Authenticator

To add the account to your Microsoft Authenticator app, follow the steps below. This is what your team mates or other peers would typically do when they start to use shared account. These instructions come without screenshots, because at least on my phone, Microsoft Authenticator does not allow to take screen shots.

1. Start Microsoft Authenticator, and click the *+ * sign above the list of accounts you have configured
2. Select *Other account (Google, Facebook, etc.) *

• Do not select any of the Microsoft options

1. On the Scan QR Code screen , click *Or enter code manually * at the bottom of the screen
2. Enter a name for the account and the authentication key, and click *Finish *.
3. Open the account, and verify that the changing one-time password matches the one that you have in Bitwarden .

Conclusion

At the end of the day, this is pretty straight forward. Personally, I am doing this whenever I create an account in Microsoft Entra ID , Azure AD B2C or Microsoft Entra External ID , that I know that I need to be able to access, even if I don’t have my phone available. Also, if I know that I am creating an account that I want to share with my team, I follow the same process.

Hope you found this article useful.

From Azure AD B2C to Microsoft Entra External ID

November 8, 2023

You may have heard that Azure AD will get a new name – Microsoft Entra ID. Even though this does not affect Azure AD B2C directly, it still might be of interest to you. Especially if you are building solutions on Azure AD B2C. You see, many of the most popular features from Azure AD B2C are already built into Microsoft Entra External ID. In this article I’ll go through the most useful features in Microsoft Entra External ID that you could use to build your solutions on top of that instead of Azure AD B2C.

Abbreviations and Acronyms

Before I dive into the article, I guess it’s a good idea to go over some abbreviations and acronyms. Azure AD, Azure AD B2C, Microsoft Entra ID and Microsoft Entra External ID are all very long names. Since I’ll be using those names quite a lot, so I better try shortening them up.

• AAD – Azure AD
• AADB2C or just B2C – Azure AD B2C
• ME-ID – Microsoft Entra ID. This is in fact the official acronym for Microsoft Entra ID, the new name of Azure AD.
• ME-EID – Although not the official acronym for Microsoft Entra External ID, I have to come up with my own, because I’ll be talking about Microsoft Entra External ID quite a lot in this article. And if I would spell out the name every time, it would be a lot of repetition.

The Future of Azure AD B2C

AADB2C is still fully supported. I have not come across any kind of end-of-life announcement for B2C either (early November 2023). So there is absolutely no need for panic, if you have built your solutions around AADB2C.

On the other hand, why would Microsoft have two cloud products with very similar features in it? Two cloud products that solve more or less the same problems? You might remember Azure Access Control Service (ACS). It used to have somewhat similar capabilities as Azure AD B2C. However, back in 2017 it was more or less discontinued , in favour of Azure AD B2C.

What really says it all for me is the following note from this overview page about Microsoft Entra External ID .

Keep in mind that the next generation Microsoft Entra External ID platform represents the future of CIAM for Microsoft, and rapid innovation, new features and capabilities will be focused on this platform. By choosing the next generation platform from the start, you will receive the benefits of rapid innovation and a future-proof architecture.

You can’t say it any clearer that that without actually saying it – Microsoft Entra External ID will eventually replace Azure AD B2C. I don’t know when Microsoft will announce that AAD B2C will be discontinued. I am not a Microsoft employee nor am I an MVP (yet). But I am willing to bet that the day will come sooner or later. Azure AD B2C will probably still be around for many years though.

Should You Switch to Microsoft Entra External ID?

If you have solutions running on AADB2C now in production, I would say that you are in no hurry at all to migrate your users and applications to Microsoft Entra External ID. I guess that all existing namespaces for ACS still work today even though you haven’t been able to create new namespaces since 2017. Similarly, all existing Azure AD B2C tenants will still work as they used to years after the last Azure AD B2C tenant was created.

But if you are planning on building a solution for managing the identities of your customers or other external users, then you should get and stay informed about Microsoft Entra External ID. At Integrata, the company I currently work for, we are building solutions where we have decided to use Azure AD B2C for managing external user identities. But now after the announcement of Microsoft Entra External ID, we have decided to switch to Microsoft Entra External ID. We have the luxury of being able to wait until Microsoft Entra External ID is ready for production use.

What is Microsoft Entra External ID

To put it short, Microsoft Entra External ID is a feature in Microsoft Entra ID (formerly known as Azure AD) to manage identities for users that are external to your own tenant, such as your customers. Currently (early November 2023), Microsoft Entra External ID is in public preview.

Currently, it looks like you can’t take an existing ME-ID tenant, and turn on the External ID features in it. However, if you log in to entra.microsoft.com in your existing ME-ID tenant, you can open the view that allows you to create a customer user, i.e. an external user. But the user creation fails when when you try to create the user. The creation fails even if you enable external user collaboration in that tenant. Remember, Microsoft Entra External ID is still in public preview, so this might be something that will change in the future.

Even if this will change in the future, I would say that it is a good thing to keep your external users in a separate tenant. It is a good thing to have a Microsoft Entra ID tenant as a security boundary between your employees and external users.

Features Supporting Identity Management for External Users

So what features are there in Microsoft Entra External ID for external users that do not exist in Microsoft Entra ID (formerly known as Azure AD)? While the list of features described below is not a complete list, at least I have found them useful in previous assignments when creating identity solutions for users from outside one single organisation.

Flexible Usernames

One of the key features you absolutely need to have is more flexible username options than you have in ME-ID. In ME-ID you can only have user accounts that use one of the domains registered with the tenant. Obviously that won’t cut it when creating user accounts for your customers or other external users. In Microsoft Entra External ID you can create user accounts using any e-mail address. You can also use more traditional usernames that don’t have to be e-mail addresses, and follow any naming convention you like. One very popular convention back in the on-prem days was the 5 + 3 convention – Take 5 first chars of your last name and append the 3 first chars of your first name. For me, that would be BerglMik.

Token Augmentation

Another very useful feature I have found myself using in most of the external user identity assignments I’ve worked with is the ability to augment the identity token with custom claims. In Azure AD B2C, this required you to write custom policies. And to create custom policies, you need to write a lot of XML. And I mean a lot . In Microsoft Entra External ID you don’t have to do that anymore. You just configure the URL of your HTTP endpoint that you want to return your custom claims, and you’re done! That’s a huge improvement!

Custom User Flows

Then there’s one more thing that I find pretty useful in cases that involve identities for external users. That is the possibility to create custom user flows for things like signing up, signing in and self-service password changes. In ME-ID you have the flows you have, and they provide very limited amount of flexibility. In Microsoft Entra External ID user flows you can customize for instance the following.

• Select how users sign in
• Add custom attributes
• Specify what attributes to collect during sign-up
• Add custom authentication extensions
• Customize translations

You also have some limited ways to modify the fields for collecting user attributes, and specifying whether a field is required or not.

Comparing Microsoft Entra External ID to Azure AD B2C

All in all, I think Microsoft Entra External ID is moving in the right direction compared to Azure AD B2C. There are two main reasons why I think so.

No More XML

First of all, you don’t have to write a huge amount of XML to resolve common uses cases. And I hope thinks stay like that too! At least for me, the feature set in Microsoft Entra External ID is enough, already in preview stage. I can’t think of a single project with external identities that I have worked on that we could not have implemented with Microsoft Entra External ID. Sure there are things that would have been nice to have. But none of them would have been a deal-breaker.

An Actual Microsoft Entra ID Tenant

The second thing that makes Microsoft Entra External ID so interesting is that it is an actual Microsoft Entra ID tenant. This was not the case with Azure AD and Azure AD B2C. This means that you have exactly the same features available for external users as you have for your employees. This brings up a few interesting use cases. Let’s say you are starting up a company, and create a tenant to host your employees’ user accounts. What if you create this tenant as a Microsoft Entra External ID tenant? If you then provision Microsoft 365 services to this tenant like Outlook, SharePoint and Teams, can you then have your customer users use this features just like your employees?

I guess that should be possible at least on an academic level, since the authority is exactly the same tenant. Needless to say that this will most certainly create some very weird scenarios. I still think that it is best to keep your external users in a separate tenant, but this is an interesting idea not to say the least. I will have to look into this a bit deeper in a future article.

UI Customization Still Missing

However, there is one feature currently missing in Microsoft Entra External ID that I really liked in Azure AD B2C. That is customizing the UI. In Azure AD B2C you can completely define your own HTML to use in your user flows. The only requirement for that HTML is that it is publicly available on the Internet, and that it contains a <div id="api" /> element. That element is a placeholder for Azure AD B2C to inject its own markup. This feature does not exist in Microsoft Entra External ID. The only way to customize your UI is to use similar branding features that you have in ME-ID. I hope that the custom UI feature comes to Microsoft Entra External ID some day. But, I can live without it too.

Further Reading

Below are some links that you might find useful when researching more about Microsoft Entra External ID.

• Microsoft Entra External ID​ public preview: Developer-centric platform
• Microsoft Entra External ID

Durable Functions Pitfalls in Azure Functions

August 29, 2023

Durable Functions is an extension to Azure Functions that allows you to write long-running workflows in code. I will not go in much detail on Durable Functions. Instead I will simply point you to this article that gives you a detailed description. In this article, I will talk about the pitfalls that I’ve fallen into several times when working with Durable Functions. Naturally, you can also consider it as best practices for Durable Functions to avoid these pitfalls. I hope that with this article I can help you along the way to perfecting your Durable Functions applications.

Brief Description of Durable Functions

I will start with a little bit of explanation about what Durable Functions is. Just to set the context of this article. But it’ll be brief. There are three different types of functions, with different features, responsibilities and constraints.

1. Orchestration Functions – The backbone of your code based workflows where you define the logic
2. Activity Functions – The workhorse of your workflows where you do all of your “heavy lifting”
3. Entity Functions – Allows you to store objects with data and are accessible to your orchestration functions

In this article I’ll focus on orchestration functions, since that is where the most pitfalls are. Orchestration functions are also the type of Durable Functions with the most constraints and potential pitfalls. I will cover entity functions in a future article, or update this one.

Orchestration Functions Must Be Deterministic

Orchestration functions *MUST be deterministic! This is probably among the first pitfalls you will fall into when working with Durable Functions. Especially if you don’t understand this properly. This means that when an orchestration function executes with the same input, it must always produce the exact same result. I can’t stress the importance of this enough!* For me, this is by far the biggest reason for running into problems with durable functions. If you are lucky, you get a runtime exception if your function violates this constraint. However, in my experience, your function just behaves in a very weird way and you spend a lot of time trying to figure out what the problem is.

OK, so what does this mean in practice? It means that each and every line of code in your orchestration must produce exactly the same result with the same input. Even if the line of code runs multiple times. And that is exactly what happens in orchestration functions. The Durable Functions runtime potentially replays an orchestration function several times. That is the price we have to pay for durability.

Let’s Look at Some Code

Let’s take a closer look at how this happens in practice. Take the very simple sample code below. It is just some meaningless code to describe the problem that you may run into.

            
[FunctionName(nameof(MyOrchestration))]

            
public async Task MyOrchestration([OrchestrationTrigger] IDurableOrchestrationContext context)

            
{

            
    Guid id = Guid.NewGuid();

            
    string id1 = context.CallActivityAsync<string>(nameof(MyActivity1), id);

            
    string id2 = context.CallActivityAsync<string>(nameof(MyActivity2), id);

            

            
    bool result = id1 == id2;

            
}

            

            
[FunctionName(nameof(MyActivity1))]

            
public async Task<string> MyActivity1([ActivityTrigger] Guid input)

            
{

            
    return input.ToString();

            
}

            

            
[FunctionName(nameof(MyActivity2))]

            
public async Task<string> MyActivity2([ActivityTrigger] Guid input)

            
{

            
    return input.ToString();

            
}

            

Now when the MyOrchestration function runs, it executes each line of code, until the first activity function (or entity function) call on the orchestration context is encountered. At that time, the durable functions runtime pauses the orchestration, and schedules the activity function with its input for execution. The runtime then executes these scheduled function in a first-come-first-served manner. So it may take quite a while before your activity function executes. There might be other orchestration instances running that have scheduled activity functions for execution. That all depends on how much load your application is experiencing. But eventually it will execute. That’s the promise of Durable Functions.

When the activity function eventually executes and returns, the runtime will replay the orchestration function, and execute each line of code again. From the beginning! The orchestration function then executes until it encounters the next activity function, and does the same thing. This is called replaying .

What Happens During Replaying?

To give you a concrete understanding of what replaying means, we can have a look at the sample code above. I’ll list the lines in the order of execution in the list below (skipping the function signatures and other irrelevant lines).

1. Line #4 : The variable id is assigned a value.
2. Line #5 : The orchestration encounters an uncalled activity function and schedules it for execution.
3. Line #14 : The activity function executes and returns a value (the value assigned to the id variable in step #1).
4. Line #4 (2nd run): The orchestration replays for the first time and assigns a value to the id variable. Note! This value is different from the value in step #1.
5. Line #5 (2nd run): The orchestration encounters an activity function that it called previously. The runtime returns the value from the execution history of the orchestration function without calling the activity function.
6. Line #6 : The orchestration encounters another uncalled activity function, and schedules it for execution.
7. Line #20 : The second activity function executes and returns a value (the value assigned to the id variable in step #4.
8. Line #4 (3rd run): Again, the orchestration function starts from the beginning, and assigns yet another value to the id variable.
9. Line #5 (3rd run): The orchestration encounters an activity function that it previously executed, and the orchestration context returns the result of that function call from the execution history.
10. Line #6 (2nd run): Another line of code that the runtime replays and returns the value from the execution history.
11. Line #8 : The orchestration compares the results of both activity functions.

In short, the executed code lines are (replayed lines are bolded): 4, 5, 14, 4 , 5 , 6, 20, 4 , 5 , 6 , 8.

As you probably have guessed, the result variable is false , and not true , as you normally would expect. This is the result of replaying. It will come back and bite you, if you don’t keep this in mind when working with Durable Functions.

How to Make Your Orchestration Functions Deterministic

In my code example above I used a Guid to demonstrate how your function can go wrong without any runtime exceptions. The same goes for timestamps and random numbers too, just to mention a few. For instance, DateTime.UtcNow returns a different value each time you call it. The Random.Next method also returns a different value each time. It wouldn’t be random otherwise, now would it?

Luckily you can fix some of these quite easily with the help of the orchestration context. The IDurableOrchestrationContext.CurrentUtcDateTime property returns a value that is guaranteed to be deterministic. The same goes for the IDurableOrchestrationContext.NewGuid method.

However, the orchestration context does not support generating random numbers. That’s no problem though. You just need to wrap your random number generation in an activity function, and you are good to go.

            
[FunctionName(nameof(MyOrchestration))]

            
public async Task MyOrchestration([OrchestrationTrigger] IDurableOrchestrationContext context)

            
{

            
    var rndInt = await context.CallActivityAsync<int>(nameof(), new Tuple<int, int>(1, 10));

            
    // rndInt is the same regardless of how many times the orchestration is replayed.

            
}

            

            
[FunctionName(nameof(GenerateRandomIntActivity))]

            
public async Task<int> GenerateRandomIntActivity([ActivityTrigger] Tuple<int, int> input)

            
{

            
    var rnd = new Random();

            
    return rnd.Next(input.Item1, input.Item2);

            
}

            

I hope that I have managed to emphasize the importance well enough with these examples. As I wrote above, I’ve spent countless hours on banging my head against anything hard around my desk trying to figure out why my application is not working as I planned. All too many times I found out that the root cause to my problems was that one of my orchestration functions I wrote was not behaving in a deterministic fashion.

Async Function Calls in Orchestration Functions

Another one of the Durable Functions pitfalls that have cause me headaches all too many times is that you *MUST NOT * call async methods in orchestration functions. The only async methods that you are allowed to call are the methods that the orchestration context defines. These functions mainly allow you to work with orchestrations, sub-orchestrations, activities and entity functions.

If you need to call any other async methods like accessing a database, you need to wrap that logic into an activity function. You cannot call the async method directly from your orchestration function.

In earlier version of Durable Functions, this used to be the case also for HTTP requests. Luckily there is now an async method on the orchestration context that helps with HTTP requests. The CallHttpAsync method allows you to do HTTP requests directly in your orchestration functions.

So, whenever you call an awaitable method in one of your orchestration functions, make sure that those calls are all going through the orchestration context.

Looping in Orchestration Functions

Depending on how you structure your code, iterating over a collection of data in an orchestration function can either follow the function chaining pattern , or the fan-out / fan-in pattern. Especially if you call activity functions in each iteration one by one, you may run into serious performance issues. This is particularly true when your activity function returns a large set of data. This is also one of the Durable Functions pitfalls that may require you to restructure your code pretty much to avoid.

Let’s start with an example. Suppose you are writing an application that processes a collection of cities and stores the hourly weather forecasts in each city for the next day in your database. You use your own database to store the cities and an external weather service to get the forecasts from. The simplified sample code below shows the setup.

            
[FunctionName(nameof(ProcessCityForecastsOrchestration))]

            
public async Task ProcessCityForecastsOrchestration([OrchestrationTrigger] IDurableOrchestrationContext context)

            
{

            
    var cities = await context.CallActivityAsync<IEnumerable<City>>(nameof(GetCitiesActivity));

            
    foreach(var city in cities)

            
    {

            
        var forecasts = await context.CallActivityAsync<IEnumerable<Forecast>>(nameof(GetCityForecastsForTomorrowActivity), city);

            
        // Here we would then store the forecasts, but we'll skip that for simplicity.

            
    }

            
}

            

            
[FunctionName(nameof(GetCitiesActivity))]

            
public async Task<IEnumerable<City>> GetCitiesActivity([ActivityTrigger] IDurableActivityContext context)

            
{

            
    IEnumerable<City> cities;

            
    // Read the cities from your database.

            
    return cities;

            
}

            

            
[FunctionName(nameof(GetCityForecastsForTomorrowActivity))]

            
public async Task<IEnumerable<Forecast>> GetCityForecastsForTomorrowActivity([ActivityTrigger] City city)

            
{

            
    IEnumerable<Forecast> forecasts;

            
    // Use an external weather service to get the weather forecast for the given city.

            
    return forecasts;

            
}

            

This code works, but is far from optimal. As the number of cities get bigger, there is more and more replaying taking place. Remember that for every activity that the orchestration encounters, the orchestration schedules the activity for execution. And when that activity completes, the runtime replays the orchestration from the start.

Replaying also involves deserializing data returned by previously executed activity functions. So, for every city in the iteration in the sample code above, there is one more activity function that already ran and returned weather forecasts. And each time, the runtime will deserialize the forecasts for the orchestration function to use.

Deserializing is generally pretty quick, but if the amount of data that is deserialized increases each time you go over an iteration, and do many iterations, it starts to slow your application down more and more. And the decrease can be very dramatic!

Looking at the Numbers

Imagine that you have 1000 cities in your database. For every city, you get 24 hourly forecasts for the next day. That is 24 000 weather forecasts each day. For the sake of simplicity, let’s also say that it takes 10 milliseconds to deserialize one hourly weather forecast.

Note! The call to the GetCitiesActivity activity function will also cause the list of cities to be deserialized for every replay, but that does not get slower for every iteration. The time is constant for every replay, which is why I excluded that from this numbers game to keep this sample as simple as possible.

So, for the forecasts returned for the first city, the deserialization will take 24 * 10 ms = 240 ms. That’s not bad. For the second city, the orchestration is replayed, and the foreach loop is played from the beginning. So to get the forecasts for the second city, we also have to deserialize the forecasts for the first city. Even though we already saved them during the first iteration. In other words, that deserialization is completely unnecessary.

Deriving from this, the time it takes to deserialize the forecasts for the second city is 24 10 ms + 24 10 ms = 480 ms. Still not that bad, but you start to get the picture, right?

Now fast forwarding to the 100th city. Before we can even get to call for the forecasts to the 100th city, we would have to deserialize the forecasts to 99 cities. With our sample values that would sum up as 99 24 10 ms = 23 760 ms. That is over 23 seconds of deserializing, all of which is unnecessary.

Getting Really Ugly

OK, so what’s the situation at the 500th city. That would mean that you’d have to deserialize the forecasts of 499 cities, all in vain. And that would cost you 119 760 ms, which is almost 2 minutes.

Remember that for every iteration except for the first one, you are doing increasingly more and more unnecessary deserialization.

The last iteration for the 1000th city, the iteration would take 4 minutes! And that’s just the last iteration!

Improving Performance

Fortunately there is quite a lot you can do to improve on the performance. The key is to avoid repeating unnecessary deserialization. Instead of having one main orchestration that would first get the forecasts with one activity function and then store them with another, you would make use of sub orchestrations and the fan-out/fan-in pattern . The sub orchestration would be responsible for getting and storing the forecasts for one single city. The code below shows how you would structure this.

            
[FunctionName(nameof(ProcessCityForecastsOrchestration))]

            
public async Task ProcessCityForecastsOrchestration([OrchestrationTrigger] IDurableOrchestrationContext context)

            
{

            
    var cities = await context.CallActivityAsync<IEnumerable<City>>(nameof(GetCitiesActivity));

            

            
    var taskList = new List<Task>();

            
    foreach(var city in cities)

            
    {

            
        taskList.Add(context.CallSubOrchestratorAsync(nameof(StoreSingleCityForecastsOrchestration), city));

            
    }

            
    await Task.WhenAll(taskList);

            
}

            

            
[FunctionName(nameof(StoreSingleCityForecastsOrchestration))]

            
public async Task StoreSingleCityForecastsOrchestration([OrchestrationTrigger] IDurableOrchestrationContext context)

            
{

            
    var city = context.GetInput<City>();

            
    var forecasts = await context.CallActivityAsync<IEnumerable<Forecast>>(nameof(GetCityForecastsForTomorrowActivity), city);

            
    // Here we would then store the forecasts for the given city.

            
}

            

            
[FunctionName(nameof(GetCitiesActivity))]

            
public async Task<IEnumerable<City>> GetCitiesActivity([ActivityTrigger] IDurableActivityContext context)

            
{

            
    IEnumerable<City> cities;

            
    // Read the cities from your database.

            
    return cities;

            
}

            

            
[FunctionName(nameof(GetCityForecastsForTomorrowActivity))]

            
public async Task<IEnumerable<Forecast>> GetCityForecastsForTomorrowActivity([ActivityTrigger] City city)

            
{

            
    IEnumerable<Forecast> forecasts;

            
    // Use an external weather service to get the weather forecast for the given city.

            
    return forecasts;

            
}

            

The performance improvements in this example come from two separate areas. First of all, the cities collection on line #4 is deserialized only two times, and not once for every city. The first time when the GetCitiesActivity function is called for the first time, and the second time when the orchestration is replayed after returning back from line #11. So 2 times instead of 1000 times.

The second performance improvement, the most significant, comes from the fact that each weather forecast is deserialized only one time. Fanning out like this dramatically decreases the number of replays, thus cutting down the time spent on doing meaningless deserialization. What this means in practice is that the iteration on lines 7-10 runs in one go, since we don’t call any sub orchestration function with the await keyword. Instead, we create a collection of tasks representing the orchestration function calls, and then await on them all together on line #11. At that point, the main orchestration would pause and wait for all of the sub orchestration functions to run and return before continuing.

You don’t have to use sub orchestrations to fan out. You can do that with activity functions as well. In this example I was just using sub orchestrations, because the sub orchestration then was calling two separate activity functions.

Cleaning up Function History

Durable Functions provides a high level of resilience towards unexpected incidents. These can be network problems, application crashes or something similar. This is achieved using persistent storage to store all orchestration, activity and entity function calls before actually performing the actions. This allows Durable Functions to recover from virtually any incident, except for deleting the storage. Even if you delete the application and recreate it and connect it to the same storage, your functions will continue running.

Over time, this storage fills up, because Durable Functions does not clean it up. This really hit me this summer when we started experiencing a lot of errors in a somewhat busy Durable Functions application that we are building. These errors were then multiplied because we used a retry policy on most of our activity calls that retried the call several times. So the work items in the history table really started piling up. At some point the storage account was the resource that incurred most of the costs in the resource group hosting our application. This was really a new situation for me, since typically storage accounts in Azure cost peanuts. At some point I think our history table was using over 100 GB!

Add Your Own Cleaning Logic

Fortunately there is quite an easy way to take care of this. The Durable Functions client defines a method, PurgeInstanceHistoryAsync , that you can call regularly to clean up the history table. The simplest way to call this is to use a timer trigger, as shown in the code below.

            
[FunctionName(nameof(CleanOrchestrationHistoryTimer))]

            
public async Task CleanOrchestrationHistoryTimer([TimerTrigger("0 0 20 * * *")] TimerInfo timer, [DurableClient] IDurableOrchestrationClient client)

            
{

            
    var statusList = new List<OrchestrationStatus> { OrchestrationStatus.Terminated, OrchestrationStatus.Completed, OrchestrationStatus.Canceled };

            
    await client.PurgeInstanceHistoryAsync(DateTime.UtcNow.AddYears(-2), DateTime.UtcNow.AddDays(-14), statusList);

            
}

            

This would run your cleanup routine every day at 20:00 UTC. It would clean up all of your history that is newer than 2 years, but older than 14 days. This would remove all instances that are marked as completed, terminated or cancelled. If you would like to clean out other statuses as well, then you can just add those statuses to the statusList collection.

To make this more robust, you could or course wrap your cleaning in an activity function that you call from an orchestration function. Then use the timer trigger to start a new orchestration instance. The code below shows you how to do that.

            
[FunctionName(nameof(CleanOrchestrationHistoryTimer))]

            
public async Task CleanOrchestrationHistoryTimer([TimerTrigger("0 0 20 * * *")] TimerInfo timer, [DurableClient] IDurableOrchestrationClient client)

            
{

            
    await client.StartNewAsync(nameof(CleanOrchestrationHistoryOrchestration));

            
}

            

            
[FunctionName(nameof(CleanOrchestrationHistoryOrchestration))]

            
public async Task CleanOrchestrationHistoryOrchestration([OrchestrationTrigger] IDurableOrchestrationContext context)

            
{

            
    await context.CallActivityAsync(nameof(CleanOrchestrationHistoryActivity), null);

            
}

            

            
[FunctionName(nameof(CleanOrchestrationHistoryActivity))]

            
public async Task CleanOrchestrationHistoryActivity([ActivityTrigger] IDurableActivityContext context, [DurableClient] IDurableOrchestrationClient client)

            
{

            
    var statusList = new List<OrchestrationStatus> { OrchestrationStatus.Terminated, OrchestrationStatus.Completed, OrchestrationStatus.Canceled };

            
    await client.PurgeInstanceHistoryAsync(DateTime.UtcNow.AddYears(-2), DateTime.UtcNow.AddDays(-14), statusList);

            
}

            

Renaming Functions

Sometimes you need to refactor your code, and restructure it. This can sometimes also include renaming methods. Under normal conditions, renaming a method is not that big of a deal. But with Durable Functions renaming functions may cause you trouble. Perhaps not one of the deepest Durable Functions pitfalls, but at least it is something you need to keep in mind.

As implied earlier, all function calls in Durable Functions are logged and stored in a history table. Each row in this table contains the name of the function, its input and output, and some other things.

When your orchestration function runs, it schedules all sub orchestrations and activities to be run. If you stop your application before they had the chance to run, then they will run after you restart your application.

Now if you stopped your application in order to update it with a refactored version where you have changed the name of a function that was scheduled for execution, there is no way that the Durable Functions runtime would know what your function is called in the updated version. This would lead into a runtime exception, and the function that the previous version had will never run.

Considerations for Renaming Functions

There is not very much you can do about this other than not to rename your functions. That’s not a good solution though. I have not had that much of a problem with this, but what I typically do is that I leave the old function as is, and write a new one with the improved functionality, and give it a new name. I typically also mark the old function as obsolete just so that I have the help of the compiler to find that function at a later time. Then update the application and let all instances pointing to the old function run out. You can then delete the old function in a future update after you’ve made sure you don’t have any instances of the old function running.

Be aware though, that orchestrations can last for a very long time. As I’ve understood it, there is not limit for how long an orchestration can last. For instance, if you wait for an external event in your orchestration, there is no upper time limit for how long the orchestration can wait for the event. You can also use durable timers to create a delay in your orchestration. Durable functions implemented in .NET support arbitrary long timers.

Monitoring Durable Functions

So how would you know what functions are running? Luckily there is an extension to Visual Studio Code called Durable Functions Monitor . With this extension you can easily connect to the task hub of your Durable Functions application and find the orchestrations you want by filtering and sorting the list of orchestrations.

With the extension you can then work with each orchestration instance and get a better view of what it has done and what is still is going to do. You can also perform actions on the orchestration with this tool such as suspend and resume, terminate and purge, just to mention a few. There’s a lot more you can do with this extension, so be sure to install it. Personally, I wouldn’t do any Durable Functions development without this tool anymore.

Examples From My Personal Experience

Now that you’ve come this far with this article, I think you deserve to get a reward for that. This time, the reward is in the form me describing perhaps my most embarrassing examples of falling into the pitfalls that I’ve described in this article. Have fun reading 😉

Creating New User Accounts

This is perhaps one of the problems that I spent the most time on trying to figure out why the heck my app was not working. It was many years ago when I was working on an Extranet solution for residents. We had a feature where residents could sign up using their Finnish bank IDs. In order not to have residents use bank IDs every time they logged in, we created a user account with their e-mail and a generated password, that we then sent to the given e-mail. The residents then used their e-mail and the generated password to log in the following times. Of course they had to change the password on first login, of course.

Already back then I was a fan of Durable Functions. And I still am. So I decided to implement the user account creation feature using Durable Functions. I created an orchestration function that called one activity function to create the user account with a random password. Then call another activity to send that e-mail address and password in an e-mail to the resident. The code below is a much simplified version of that logic.

Sample Code

            
[FunctionName(nameof())]

            
public async Task CreateAndSendUserAccountOrchestration([OrchestrationTrigger] IDurableOrchestrationContext context)

            
{

            
    var email = context.GetInput<string>(); // Assume the e-mail address is sent as input to the orchestration.

            
    var pwd = this.GenerateRandomPassword();

            

            
    var accountInfo = new Tuple<string, string>(email, pwd);

            
    await context.CallActivityAsync(nameof(CreateUserAccountActivity), accountInfo);

            
    await context.CallActivityAsync(nameof(SendUserAccountActivity), accountInfo);

            
}

            

            
[FunctionName(nameof())]

            
public async Task CreateUserAccountActivity([ActivityTrigger] Tuple<string, string> input)

            
{

            
    // Here we would use the username and password sent in the input to connect to our user registry

            
    // and create a new user account.

            
}

            

            
[FunctionName(nameof())]

            
public async Task SendUserAccountActivity([ActivityTrigger] Tuple<string, string> input)

            
{

            
    // Here we would take the username and password from the input, add that information to an e-mail template

            
    // and send it to the given e-mail address.

            
}

            

            
private string GenerateRandomPassword()

            
{

            
    string pwd;

            
    // Use System.Random or some other mechanism to generate a random password and return it.

            

            
    return pwd;

            
}

            

Very innocent looking code, don’t you think? But since you’ve now read this article, you probably immediately spot the problem. We’ll I did not! I got the user account created, and the e-mail was sent properly. But when I tried to log in, I got a login failed error. Every time! Incorrect username and/or password!

A Very Easy Solution

I don’t remember how many times I deleted the generated user account and retried the whole thing. The same result every time. I could not understand what was going wrong. It was really a mystery. I even used break points in the activity functions to step through them. Yes, my code was in fact creating a user account, and yes, my code actually sent the e-mail. There was only one orchestration instance running at a time. I made sure of that to ensure that there was no mixing of data between orchestration instances.

It wasn’t until I started looking closer at the inputs to the activity functions that I pretty quickly realized what the problem was. My code generated the password twice! One password that I used to create the user account with. And another password that I sent out in the e-mail. Afterwards, I’ve been trying to figure out how on earth did I not notice that earlier. Can’t say for sure, but the only thing I can think of is that the call to the GenerateRandomPassword() method looks so innocent, since it is not an async function. Well, we all know better now, don’t we?

So, I simply wrapped the password generation logic in an activity function. The problem was solved with just a few additional lines of code. I am still beating myself over this, and how could I have been so blind. Enough time has now elapsed, and at least I can now share it as a funny lesson.

Further Reading

Here is a list of links that I think provide you with additional information when working with Durable Functions. Hopefully you have found this article useful.

• What are Durable Functions?
• Durable Functions types and features
• Orchestrator function code constraints
• Durable orchestrations
• Sub-orchestrations in Durable Functions
• Durable Functions Monitor
• Durable Functions billing
• My other Durable Functions articles

Resolving the \u201CCould Not Load File or Assembly System.IdentityModel.Tokens.Jwt\u201D Error

December 9, 2022

I was working on an Azure Functions application to create a REST API that accepts bearer tokens. When I fired up the app in Visual Studio, I was greeted with the following error message.

Could not load file or assembly 'System.IdentityModel.Tokens.Jwt, Version=6.23.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35'. The system cannot find the file specified.

This article describes the steps I took to resolve the issue for my Azure Functions application.

Could Not Load File or Assembly – Fix #1

The first fix was quite easy to find on Google . There are many posts that talk about a problem in the Azure Functions SDK. It seems that the SDK is too eager to clean out referenced assemblies that it thinks are not used. So, you need to instruct the Functions SDK to skip cleaning out by adding the following property group to the Azure Functions app project file.

            
<PropertyGroup>

            
    <_FunctionsSkipCleanOutput>true</_FunctionsSkipCleanOutput>

            
</PropertyGroup>

            

That fixed the issue for me when running locally in debug mode in Visual Studio.

Could Not Load File or Assembly – Fix #2

That was an easy fix, I thought, so I deployed the application to my Azure App Service and fired off a request to one of the endpoints. However, I got the same error message as I did earlier.

Could not load file or assembly 'System.IdentityModel.Tokens.Jwt, Version=6.23.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35'. The system cannot find the file specified.

Oh snap! Using the App Service Editor, I verified that the System.IdentityModel.Tokens.Jwt.dll assembly really was not available in the bin folder. A lot of files, but unfortunately not the required. So apparently the _FunctionsSkipCleanOutput property did not fix everything.

I noticed that my Functions app did not contain a direct reference to System.IdentityModel.Tokens.Jwt but instead, my Functions app references another library, that had a reference to the Tokens assembly. So, I thought that I could easily fix the error by adding a direct reference to the missing package to my Functions app too.

But no. I was wrong! Still, the same error. I realized that if the Functions SDK incorrectly cleans out unused assemblies, it might not be enough just to add a reference to it. I would need to use it too. So I added the following code to the constructor of one of the function classes I had in my project.

            
using Microsoft.Extensions.Logging;

            
using System.IdentityModel.Tokens.Jwt;

            

            
public class ReportsFunctions

            
{

            
    public ReportFunctions(ILogger<ReportsFunctions> logger)

            
    {

            
        var token = new JwtSecurityToken();

            
    }

            
}

            

Now, when I deployed this project to Azure, it started working. I also verified that the System.IdentityModel.Tokens.Jwt.dll now was present in the bin folder.

Conclusion

After the second fix I thought that maybe I don’t need the first fix. The second fix would fix all my problems. That is however not true. Seems that you still need Fix #1, even after applying Fix #2. At least when running the app locally. And Fix #2 is not something that I found by Googling, so I hope this tip will come in handy, should you end up on this page one day.

Blazor Authentication with JWT Token Using Blazorade MSAL

March 1, 2022

Lately I’ve been working a bit on Blazorade MSAL and updating it to work with .NET6. At the same time, I thought I’d write a sample application that demonstrates how to do Blazor authentication with JWT tokens when connecting to Microsoft Graph. When working on that sample application, I came up with a few improvements to Blazorade MSAL. These improvements make it super easy to implement Blazor authentication with JWT tokens to connect to any REST API. This article describes the most important parts of this sample application. You find the sample application on Github .

Overview

When talking about Blazor authentication with JWT tokens , I’m referring primarily to access tokens. Your Blazor application uses these tokens to authenticate to a REST API on behalf of the user. This is also called delegated permissions – A user delegates permissions to an application. In the sample application described in this article, I’ll cover connecting to Microsoft Graph . But the same principles applies to any Blazor application that implements authentication with JWT access tokens. You can even create your own REST APIs with for instance Azure Functions and use JWT tokens from your Blazor application.

Set Up for First Use

This sample application requires a settings file that contains information about your application. I’ve intentionally left this information out of the repository. Application settings typically contain sensitive information.

Detailed instructions for setting up the sample application on your local computer is available in the source code repository .

If you haven’t used Blazorade MSAL before, be sure to check out this introduction section .

Implementing Blazor Authentication With JWT Tokens

Now that you have the sample application configured to run on your local computer, it’s time to have a closer look at it. I’m not going to go through all of the application, but only highlight the main points.

The sample application sends HTTP requests to Microsoft Graph . This application does that by using HttpRequestMessage objects. These object are “pre-authenticated” by the BlazoradeRequestFactory service class implementation. The service class is injected on the Index page , as shown below. I’ve also injected an HttpClient service, because I’ll use that later on when sending the requests.

            
@page "/"

            
@inject BlazoradeRequestFactory RequestFactory

            
@inject HttpClient HttpClient

            

With this, all you have to do now to get a request object is to call the RequestFactory as shown below.

            
using(var request = this.RequestFactory.CreateGetRequestAsync("https://graph.microsoft.com/v1.0/me", "User.Read")

            
{

            
    using(var response = await this.HttpClient.SendAsync(request))

            
    {

            
        // Process the response here...

            
    }

            
}

            

What Happens Behind the Scenes?

This looks pretty simple, right? That’s the added value of Blazorade MSAL! However, there’s a lot going on behind the scenes though. First of all, the BlazoradeRequestFactory uses the BlazoradeMsalService service to acquire an access token for the current user that grants the User.Read permission. This permission is required when calling the /me endpoint in Microsoft Graph .

The BlazoradeMsalService uses the JavaScript version of MSAL to acquire an access token. That JavaScript library caches the tokens for you. If a valid token does not exist in the cache, MSAL will take the user to the authentication process. In case the user has not consented to the permissions requested by your application, the login process will show the consent dialog too. If the authentication passes, and the user consents to the requested permissions, MSAL will return the access token to the BlazoradeMsalService .

Now the BlazoradeMsalService hands over the access token to the BlazoradeRequestFactory service. This service then creates an HttpRequestMessage object instance pointing to the URL specified by your application, and adds the access token as bearer token in the authorization header. The request will then be returned to your application. All you now have to do in your application is to use the injected HttpClient service to send away the request and handle the response.

Further Reading

To learn more about Blazorade MSAL, check out my other Blazorade MSAL articles .

Azure DevOps Project Lifecycle – From Sales to Production

February 10, 2022

In this article I thought I’d write about something not so technical – Azure DevOps Project Lifecycle. Did you know that Azure DevOps is not just for developers and architects? You can get a lot of benefit from Azure DevOps already during the sales phase of a new project.

Very often when talking about project lifecycle, not just in Azure DevOps, we tend to focus only on Design – Build – Test – Deploy .

[](https://mikaberglund.com/wp-admin/edit.php?post_type=post)

Project-Lifecycle-1024x425

But, there’s a lot that happens before you even get to the Design phase. And that is the sales phase. In my experience, companies very often tend to handle the sales phase very much isolated from the actual implementation phases.

But it shouldn’t be that way. And with Azure DevOps it does’t have to be that way either.

Introduction

So what’s the problem I’m trying to solve? To put it short, it’s the complete disconnection between work estimates that you give during the sales phase and the features and functionality that you design and build during a project. I’ve seen this so many times in different companies.

Here is a scenario that I believe is quite common. You can probably recognize at least some of these phases.

• Request for Proposal
• A potential customer sends you an RFP for something they want you to build
• The RFP contains a detailed, prioritized and categorized list of requirements
• The requirements list is very often an Excel workbook
• The customer wants you to add your work estimates to the requirements list

• Proposal
• Your sales team produces a proposal
• The sales team asks a potential implementation team to participate in the work estimation

• Adjustments
• After the initial proposal, you typically iterate over the requirements with the potential customer
• Often some features are moved to later phases
• Requirements are reprioritized and recategorized
• Work estimates can change based on better insights into customer requirements

• Implementation
• In an ideal world the customer would accept your proposal
• You start the implementation, sometimes with a different team than the one responsible for work estimation
• During requirements workshops, you add Feature and User Story work items to your backlog
• The implementation team processes the backlog and adds their work estimates to the work items

At this point, the original requirements list is already quite disconnected from the work that you have planned to start working on. Sometimes the original work estimates that your sales team sold are completely different from what you have planned.

Solving the Problem With Azure DevOps

Did you recognize the situation I described above? Do you think that it may be a problem in your organization too? If so, then I suggest you continue reading.

The solution is actually pretty simple. You just create your Azure DevOps project already before starting to work on your proposal. Then you add all the features and requirements you got from the customer as Feature work items, and add your work estimations using the Effort field. If you want, you can also prioritize the features using the Business Value field.

Then use the Sprints in Azure DevOps to associate the features with different phases. You might also want to map your features to Epic work items. This is especially useful if your customer has categorized the features in the RFP with different business initiatives.

Connecting to Azure DevOps From Excel

To open your Features Work Items in Excel, you need to install the Azure DevOps Office Integration add-on from Microsoft. After that, you need to build a query that returns the Feature work items you want to include in your proposal. The Office Integration add-on adds a *Team * tab to the Office ribbon in Excel.

image

All you have to do now is to open the query you created by using the New List button. By default, the Work Items returned by the query will show up like this.

image-1-1024x150

From here on you just need to apply some Excel magic to make your features and work estimates look something like in the pictures below.

Feature-table-2-1024x395

Feature table with descriptions

image-2

The Feature table converted into a Pivot table

These tables and pivot tables are very similar to what you typically have in proposals. In case you need to iterate over the phases, prioritization and even your work estimates, you do that work in Azure DevOps. When you are done, you just hit the Refresh button in Excel, and you have an updated version for your customer right away.

Compared to disconnected tables in a Word document, these present a huge advantage for you. They contain actual Azure DevOps Work Items that your development team will start working one once your proposal is approved. And that means that you have a better chance of delivering your project within the given work estimates. And that will result in happier customers and better profit. Wouldn’t you agree?