The problem with general-purpose AI agents is that they are subject to “hallucinations” (these days, we say that those agents produce answers that aren’t “grounded”).

One solution to that problem is to create a custom AI agent with your own content and have your agent use that content to generate grounded answers (this is referred to as Retrieval Augmented Generation or RAG). Effectively, you can create a dedicated, reliable AI assistant for your users for any aspect of your organization.

Progress Telerik Document Processing Libraries (DPL) include a set of AI connectors that support creating those custom RAG-enabled AI agents of your own using any of the existing Large Language Models (LLMs) available to you in Azure or on your own computer/server using Ollama. And, once that agent is created, Telerik UI tools will let you integrate it into any application.

So, this post kicks off a series of posts where I’m going to walk you through all of the steps you need to create a custom AI agent by using Telerik DPL (and related AI tools), integrated with an LLM available on Azure or in Ollama. Once you’ve created an agent, I’ll show you how to add that custom agent into your application’s UI using AI-enabled Telerik UI components in either JavaScript or Blazor (though you could also create your frontend in ASP.NET, Windows Forms or .NET MAUI).

But … having said that, if all you want to do is add an AI prompt to your application, then, thanks to Telerik tools, this post might be the only one you need. At the end of this post, I’ll show you how to create a simple frontend for your application to use your LLM. In fact, if you’ve already got an LLM deployed (which is what this post is about), you might want to skip the rest of this post and go directly to that last section.

Picking Your LLM Provider

If you stick with Microsoft’s offerings, you actually have three options for creating the LLM your application will use. The good news here is that, thanks to Microsoft and Telerik tools, it doesn’t make much difference to your code which of those three options you use.

Your three choices are:

• Microsoft Foundry: This gives you access to a wide variety of LLMs from multiple providers (including the OpenAI LLMs), while giving you integration with Azure security. Microsoft Foundry also gives you extensive monitoring for your LLM, enables data privacy and supports integration with other Azure services. This is Microsoft’s recommended option. I’ll call this the “Foundry option.”

• Azure OpenAI: This is the easiest option to set up but also provides the least access to Azure functionality. The Azure OpenAI option gives you access only to OpenAI’s LLMs and only limited integration with other Azure resources (principally, security). With this choice you do, however, get access to the latest OpenAI LLMs, potentially before they show up in Microsoft Foundry. I’ll call this the “OpenAI-only option.”

• Ollama: Unlike OpenAI or Microsoft Foundry, Ollama runs on your local computer, rather than in the cloud. Since there are no API fees, that makes Ollama an attractive choice for cheaper solutions (provided you have a powerful enough development computer). I’ll call this the “Client-side option.”

Setting Up OpenAI/Microsoft Foundry

While I’m treating the OpenAI-only option as a separate case from the Foundry option, the OpenAI-only option is actually hosted in Microsoft Foundry. As a result, the processes for setting up the OpenAI-only or the Foundry option are very similar:

1. In the Azure portal at portal.azure.com, create an Azure resource.
2. In the Microsoft Foundry portal at ai.azure.com, add an LLM—a “deployment”—to that resource.

Creating the Resource

To start, surf to the Azure Portal and search for Microsoft Foundry. On the Microsoft Foundry page, in the menu on the left, expand the Use with Foundry node and click on either:

• The Foundry node for the Foundry option
• The Azure OpenAI node for the OpenAI-only options

Either choice will open a page on the right. On that new page, click on the +Create menu choice at the left end of the menu running across the top of the page. That will start the wizard that will create your Azure resource.

If you opened this page from the Foundry node, you’ll start the wizard for creating your Foundry resource.

If you opened this page from the OpenAI node, you’ll get a dropdown list with two choices: OpenAI and Microsoft Foundry. This is, effectively, your last chance to switch to the Foundry option instead of OpenAI-only. Pick the OpenAI choice to open the wizard for creating an OpenAI-only resource.

Regardless of which wizard you’ve invoked, on the wizard’s first page you’ll need to provide a resource group, a name for your resource and a region for your LLM to run in. In addition, on the first page:

• For a Foundry resource, you’ll need to provide a default project name
• For an Azure OpenAI resource, you’ll need to select a pricing tier

After that, it’s just a matter of “Next”ing your way through the rest of the wizard’s tabs.

Setting Network Access

Both the Foundry and OpenAI-only wizards include a Network tab to control access to your resource. You have three choices on the Network tab:

• All networks: Gives access to your resource from anywhere
• Selected networks: Limits access to a subnet on a specific Azure virtual network, plus a list of IP addresses (e.g., your development computer)
• Disabled: Allows access only through a private endpoint on an Azure virtual network

You would use the last two options if you were going to run your application on a VM on a virtual network or in an App Service. You don’t need to use the network choices to control access to your resource. You could control access to your LLM just through the resource’s Access Control/IAM roles, for example, or your application’s built-in security. However, for a production application, you should always lean toward more control rather than less and pick whichever of these options that makes sense for limiting network access to your resource.

Setting Foundry Option

The Foundry wizard includes three additional tabs that the OpenAI wizard does not:

• Storage: This tab provides access to multiple additional Azure resources. You can:
      » Tie your resource to an Azure Key Vault where you can store passwords or other credentials that agents in your resource will need
      » Turn on Application Insights to log activities in your resource
      » Tie in an AI Search agent that your resource can access when processing requests
      » Add a Storage account to hold uploaded files
      » Integrate a CosmosDB account to hold conversation history.
• Identity: Assign a Managed Identity to your resource to support agents that access other Azure resources
• Encryption: Use your own encryption keys for any data stored by your resource

For a proof-of-concept project, you can take the defaults on all these tabs.

Both wizards finish with the standard Tags tab and Review-and-create tab. When you get to that last tab, click the Create button to create your resource.

Selecting an LLM

Your application interacts with a deployed instance of some LLM so your next step is to create a deployment that uses one of the LLMs available to your resource.

To do that, navigate to your resource and, on the Overview page, click on the Go to Foundry portal link at the top of the page. This will open a new tab in your browser displaying the ai.azure.com portal. This is where you will select the LLM you’ll use in your deployment.

To create a deployment, on the Microsoft Foundry page for your resource, in the menu on the left, click on the Model catalog node. That will take you to a page where you can select your LLM.

A warning: Over and above whatever criteria you have for getting the right model for your application, selecting a model may require some trial-and-error poking around. That’s because:

• Some models are deprecated or may not be available for your resource (e.g., selecting a non-OpenAI LLM for an OpenAI-only resource).
• You may not be eligible for some models.
• Your subscription may not have the necessary resources to support a model.
• The model you select may not support the processing you want to implement.

Once you open the page listing available LLMs, if you got to the page from a:

• Foundry resource: You can browse the lists of LLMs from a variety of providers or you can search for an LLM using the search box just below those lists
• OpenAI resource: You can browse the list of OpenAI LLMs

When you select an LLM, Azure will display a page with high-level information about your LLM. For my case study, I created three deployments, one each for these three LLMs:

• gpt-5.2-chat LLM as an example of a Foundry resource
• gpt-5-chat LLM as an example of an Azure OpenAI-only resource
• text-embedding-3-large as an example of an LLM with specific features (I’ll use it in a later post on querying with Telerik AI connectors).

Creating a Deployment

To create your deployment, at the top of the page, click the button labeled “Use this model.” That will display a dialog where you can customize the LLM you’ve chosen, including giving your deployment a name (your deployment’s name will default to the name of your LLM). Click on the button at the bottom of the page labeled “Create resource and deploy” … and then be patient because this can take a moment.

After your deployment is created with your selected LLM:

• In a Foundry resource, you’ll be taken to the page describing your deployment.
• In an OpenAI-only resource, you’ll be taken to an Overview page. In the menu on the left, click on the Models + endpoints node to open a list of your deployments. Select the deployment you just created to be taken to the page describing your deployment.

Once you’re on your deployment’s page, you need three required pieces of information from the page to use in your application and one optional piece:

• Name: Displayed at the top of the page.
• Authentication information: Your deployment will default to Key authentication, which is fine for a proof-of-concept application (you can switch to Entra Id authentication for production, but the code to access your resource will get more complicated). Assuming that you stick with Key Authentication, copy the Key provided on this page.
• URL: At the top of your deployment’s page, find the Target Uri and copy the first segment of the URL provided (i.e., everything from the “https://” and up to, but not including, the first forward slash in the URL).
• Version: Depending on how you intend to use your LLM, you may not need this, but it does no harm to grab it now. Again, the easiest place to get this is from the sample code. Look for the string put in the variable called api-version (it will look like a date, e.g., “2025-12-01”).

Returning to Your Deployment

To return to your resource or your model, first surf to ai.azure.com and sign in. This portal is, currently, in the process of migrating to a new UI, so:

• If you get the “old” UI then, you may get a list of Foundry and Open AI resources. If so, pick the resource you want to go to the resource’s page. On the other hand, you may just be taken directly to one of your resources. Either way, in the menu on the left, select the Models + endpoints node to see a list of your deployments.
• If you don’t get that list of your resources … well, then you’re probably in the new UI and, at this point, I’d recommend using the toggle at the top of the page to return to the old UI so you can follow along.

You have more to do to create your own custom RAG-enabled AI agent (load your own content, for example). But if all you want is an application that integrates an AI prompt, you’ve done everything you need to support that. You just need to create a frontend that lets the user query your LLM’s deployment. The Telerik AI Prompt will let you do that with minimum effort. I’ll cover that after showing how to set up the client-side option with Ollama.

Setting Up Ollama

To implement the client-side option, you first need to download Ollama and install it. To confirm that Ollama installed successfully, open a command window and enter ollama. You should get back a list of Ollama commands.

You next need to add the LLM you want to use to Ollama. To do that, open a command window and use Ollama’s pull command to install one of the LLMs from the Ollama registry. This command installs OpenAI’s gpt-oss LLM:

ollama pull gpt-oss

After using the pull command, you can use Ollama’s list command (which displays the installed LLMs) to confirm your installation.

The Ollama server should start automatically after installation (and after every reboot) and should be listening on port 11434 on localhost. You can confirm that by using Ollama’s serve command. If server isn’t running, it will start and report the address the server is listening on. If the server is already running, you’ll get an error message that includes address that Ollama is listening on.

Make a note of the address (probably http://localhost:11434) and the name of the LLM you installed—you’ll need both in your code.

I’m building up to a creating a custom AI agent over this series of posts. But, at this point, you’ve done everything you need to create an application with an AI prompt—it’s just a matter of adding a frontend to your LLM.

Adding a Front End

In my next posts, I’ll use Telerik Document Processing Library tools to create applications that allow users to apply AI to documents. However, once you’ve created an LLM deployment, you can tie that deployment into your application’s UI with a few lines of code in your application’s Program.cs file and then query your LLM through the Telerik AI Prompt component in your application’s UI.

To do that in a .NET 8 or later application, you first need to add the Microsoft.Extensions.AI.OpenAI NuGet package to your application. After that, you need to tie your model into your application by adding the following code to your application’s Program.cs file, inserting the information about your LLM that you gathered from your deployment’s information page.

For either of my Foundry or OpenAI-only options that code looks like this:

builder.Services.AddSingleton(new AzureOpenAIClient(
     new Uri(“<url>”),
     new AzureKeyCredential(“<key>”)
 ));
builder.Services.AddChatClient(services => 
         services.GetRequiredService<AzureOpenAIClient>()
            .GetChatClient(<deployment name>).AsIChatClient());

For Ollama, in addition to adding the Microsoft.Extensions.AI.OpenAI NuGet package, you’ll also need to add the OllamaSharp and Microsoft.SemanticKernel.Connectors.Ollama packages. After that, this single line of code will integrate Ollama into your application:

builder.Services.AddSingleton<IChatClient>(
    sp => new OllamaApiClient("<Ollama address>", "<model name>")
);

Your last step is to add the Telerik AIPrompt to your application’s UI (available in JavaScript for Kendo UI, Blazor, ASP.NET AJAX, WinForms and .NET MAUI). That can be as simple as this in an application that supports Razor (e.g., ASP.NET or Blazor):

<TelerikAIPrompt/>

And that would give you this UI:

In a JavaScript application, you’ll need to add a <div> element, set the element’s id attribute, and write a couple lines of JavaScript code. I’ll cover that in a later post in this series.

You can now start your application, enter a prompt into the AIPrompt component (e.g., “Tell me about RAG-enabled AI applications”) and get a response.

There’s obviously far more that you can do with the AI Prompt … and I’ll return to that after my next post. Before that, however, I’m going to roll in Telerik Document Processing Library to let you load the content for your custom AI agent.

Explore Telerik Document Processing Libraries, plus component libraries, reporting and more with a free trial of the Telerik DevCraft bundle:

Try DevCraft

Progress Telerik Document Processing Libraries, in addition to letting you work with a variety of document formats (PDF, DOCX, RTF, HTML, XLSX and more), are an example of the reason you buy into a suite of tools: All the tools bear a “family resemblance.”

The ideal scenario, of course, would be for a single tool that made all these document formats look the same. Given the differences in format and functionality between, for example, a PDF, a Microsoft Word (or RTF or HTML) document and an Excel spreadsheet, that’s not reasonable (though Progress Telerik has achieved that with DOCX, RTF and HTML documents).

The good news here is that, with Telerik Document Processing Libraries (DPL), the family resemblance is strong enough that, for all of the document types the library supports, I can show you how to load documents, start the editing process, convert between various document types and save a document in this one post.

Configuring Your Project

The sample code in this post was all written using the DPL for Windows libraries (even though I was working in ASP.NET Core—the more technical name for the version I used is “.NET(Target OS: Windows).” The suite is also available for the .NET Framework.

To create an ASP.NET Core project that would work with “all the documents,” I added these NuGet packages to my project:

• To work with PDF files: Telerik.Windows.Documents.Fixed
• To work with DOCX, HTML and RTF files: Telerik.Windows.Documents.Flow
• To work with Excel spreadsheets: Telerik.Windows.Documents.Spreadsheet

For the Excel spreadsheets, I’m only going to work with XLSX files, so I added the Telerik.Windows.Documents.Spreadsheet.FormatProviders.OpenXml package to my project. (If I was going to work with, for example, XLS spreadsheet, then I would have added the Telerik.Documents.Spreadsheet.FormatProviders.Xls package.)

Loading Your Document

The code to load a document from a file into any of these libraries is very similar:

1. Create the appropriate provider.
2. Use the .NETFile object’s OpenRead to create a Stream that points to the file.
3. Use the provider’s Import method to load the stream into the document object.

Here, for example, is the code to load a PDF file into a RadFixedDocument object (I used this code in an ASP.NET Core application with documents in my project’s wwwroot folder):

RadFixedDocument doc;
PdfFormatProvider prov = new();

using (Stream str = File.OpenRead(@"wwwroot/documents/Priorities.pdf"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

And here’s the code to load a DOCX file into a RadFlowDocument:

RadFlowDocument doc;
DocxFormatProvider prov = new();

using (Stream str = File.OpenRead(@"wwwroot/documents/Priorities.docx"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

As you can see, the code is identical except for the provider (PdfFormatProvider vs. DocxFormatProvider) and document objects (RadFlowDocument vs. RadFixedDocument).

Because both RTF and HTML documents load into the same RadFlowDocument object as a DOCX document, only the provider object changes (HtmlFormatProvider or RtfFormatProdiver instead of DocxFormatProvider) when working with those file formats. Here’s the code to load an RTF document:

RadFlowDocument doc;
RtfFormatProvider prov = new();

using (Stream str = File.OpenRead(@"wwwroot/documents/Priorities.rtf"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

And here’s the almost identical code to load an HTML file:

RadFlowDocument doc;
HtmlFormatProvider prov = new();

using (Stream str = File.OpenRead(@"wwwroot/documents/Priorities.html"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

The code to load an Excel workbook is also similar to what you’ve seen before, just swapping in a new document object (Workbook) and provider (XlsxFormatProvider):

Workbook doc;
XlsxFormatProvider prov = new();
using (Stream str = File.OpenRead(@"wwwroot/documents/priority.xlsx"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

A note: The Workbook object assumes that you’re going to load the whole Excel workbook into memory. For very large workbooks, that may not make sense. For that scenario, you should look at the SpreadStreamProcessing Library.

Modifying the Documents

Once you’ve loaded the documents, you can start working with them. You can often simplify your code by using the RadFixedDocumentEditor with PDF documents or the RadFlowDocumentEditorwith Word/RTF/HTML documents. Not surprisingly, the code for creating an editor is almost identical for these two document types: create an editor object and pass the document you want loaded into the editor.

The code to create an editor for a PDF document looks like this:

RadFixedDocumentEditor editor = new RadFixedDocumentEditor(doc);

The code for Word/RTF/HTML documents looks like this:

RadFlowDocumentEditor editor = new RadFlowDocumentEditor(doc);

That’s not to say that, as you start working with those documents, there aren’t going to be differences. These are, after all, very different kinds of documents. Having said that, some functionality does work in a similar way across all the document types.

If, for example, I want to search a PDF document for the text “ASP.NET,” I create a TextSearch instance from my document object. I then use the TextSearch object’s FindAll method to search for text in my PDF document, passing two things: my search text and a TextSearchOptions object that specifies how I want my search conducted. That FindAll object returns a collection of SearchResult objects that I can loop through.

Typical code, then, looks like this:

TextSearch search = new TextSearch(doc);
TextSearchOptions opts = new() {
CaseSensitive = false,
WholeWordsOnly = true,
UseRegularExpression = true
                                                              };

IEnumerable<SearchResult> items = search.FindAll("ASP.NET", opts);

Debug.Print($"Found {items.Count()} items.");
foreach (SearchResult item in items)
{
    Debug.Print($"Found at {item.Range.StartPosition} ");
    Debug.Print($"Found: {item.Result}");
}

The process is almost identical for the RadFlowDocument object, except:

• You call the FindAllmethod directly from the RadFlowDocumentEditor.
• There isn’t a separate options object (though all the search options from the TextSearch object are still available).
• The FindAll method on the editor returns FindResult objects instead of SearchResult objects.

As a result, the equivalent search code for a DOCX, RTF or HTML document looks like this:

RadFlowDocumentEditor editor = new RadFlowDocumentEditor(doc);

IEnumerable<FindResult> items = editor.FindAll("ASP.NET");

Debug.Print($"Found {items.Count()} items.");
foreach (FindResult item in items)
{
    Debug.Print($"Found at {item.RelativeStartIndex} ");
    Debug.Print($"Found: {item.FullMatchText}");
}

Searching a spreadsheet works similarly. The differences:

• The FindAll method is built right into the Workbook object.
• You have more search options available with the spreadsheet object.
• You pass your search string as part of the options object.

My find code with a workbook would look like this:

FindOptions opts = new() {
FindWhat = "ASP.NET",
MatchCase = false,
MatchEntireCellContents = true,
                                                };

IEnumerable<FindResult> items = doc.FindAll(opts);

Debug.Print($"Found {items.Count()} items.");
foreach(FindResult item in items)
{
    Debug.Print($"Found at {item.FoundCell.CellIndex} ");
    Debug.Print($"Found: {item.ResultValue}");
}

One note: It is certainly convenient when objects from the different libraries share the same name (like the FindResult object that’s defined in both the RadFlowDocument and Workbook libraries). However, if you try to use both FindResult objects in the same code file, the compiler will get confused because the two objects are in different namespaces. In the unlikely case that you’re working with both Excel and Word documents in the same code file, you’ll have to fully qualify the object names—something I haven’t done in this post.

Saving Your Documents

To save your modified documents back to disk, you just need to use the provider’s Export method. The code for all the document types is identical:

using (Stream str = File.Create(@"wwwroot/documents/Prioritiesnew.<filetype>"))
{
    prov.Export(doc,str, TimeSpan.FromSeconds(10));
}

Converting Documents

You can convert from one type in the suite to other types and, not surprisingly, the conversion processes look very much alike. As you’ve seen before, it often comes down to using the right provider.

If, for example, you want plain text version of your PDF file, you use the TextFormatProvider object’s Export method:

TextFormatProvider prov = new();
string text = prov.Export(doc, TimeSpan.FromSeconds(10));

For Word/HTML/RTF document types, the code is almost identical except it uses the TxtFormatProvider object:

TxtFormatProvider txProv = new();
string text = prov.Export(doc, TimeSpan.FromSeconds(10));            

One note: There is a downside to having the classes that do similar things to different document types have the same name. If you are mixing document types and, as a result, using the Fixed, Flow and spreadsheet libraries in the same application, the compiler can get confused about which class from which library you’re using. If so, you’ll have to fully qualify your class names by including their namespaces in the class names. That makes for hard-to-read code, so I haven’t done that here.

But, as an example of how different documents require different functionality, you probably wouldn’t ever want to convert an Excel workbook to a string … but you might want to save your workbook as a CSV file. As you might expect by now, the code to save your imported workbook into a CSV file just means using the Export method on the appropriate provider—the CsvFormatProvider object in this case.

Typical code would look like this:

CsvFormatProvider prov = new();

using (Stream str = File.Create("Priority.csv"))
{
    prov.Export(doc, str, TimeSpan.FromSeconds(10));
}

Converting any of these document types (Excel, Word, HTML, etc.) to PDF is equally straightforward. Because all the libraries look very much alike, it’s really just a matter of adding the library with the provider you need.

But you can also convert your Workbook object into a RadFixedDocument if you wanted to manipulate your spreadsheet as a PDF object. That conversion is handled by the PdfFormatProvider from the Telerik.Windows.Documents.Spreadsheet.Formatproviders.Pdf package and using its ExportToFixedDocumentmethod:

PdfFormatProvider prov = new();

RadFixedDocument fixedDoc = 
        prov.ExportToFixedDocument(doc, TimeSpan.FromSeconds(10));

The code is identical if you want to convert a Word/RTF/HTML document to a RadFixedDocument to work with it as a PDF file. That conversion also uses a PdfFormatProvider object but, this time, from the Telerik.Windows.Documents.Flow.FormatProviders.Pdf namespace.

But, because the providers from the two libraries have the same name, if you’re using both libraries in the same code file, you will need to fully qualify your provider names to make sure you’re getting the appropriate PdfFormatProvider.

Of course, once you start using these tools to create or modify the documents you’ve loaded, you’ll find more differences—the functionality in a spreadsheet is very different from the functionality in an HTML document. But, while the family resemblances among this suite won’t eliminate those differences, it does cut those differences down to what matters: how those documents differ in their functionality. Which is, after all, what you want.

Explore Telerik Document Processing Libraries, plus component libraries, reporting and more with a free trial of the Telerik DevCraft bundle:

Try DevCraft

If you have ever built a model-powered agent, you know the development loop. Write some code, fire it at the endpoint, check the response, tweak the parsing, fire it again. Repeat until the output looks right. It is a perfectly normal workflow—and it quietly drains your token budget with every single iteration.

The new Progress Telerik Fiddler Everywhere Agent Cache feature is designed to break that cycle. Once you capture a response from a model-provider endpoint, you can flip a single switch and have Fiddler software replay that response for every subsequent matching call—without the request ever leaving your machine. Same output, zero additional tokens consumed on the provider side.

This post walks through exactly how that works, using a small open-source demo project to make everything concrete.

The Hidden Cost of Agent Development

Building an agent that calls a completion endpoint involves a lot of repetition that has nothing to do with the model itself. You are iterating on:

• How you construct the prompt
• How you parse and validate the structured response
• How you surface the result to the rest of your system
• How your error handling behaves when the response is malformed

None of those iterations require a new, unique response from the model. You already have a good one from the first call. But unless you manually save the raw response and mock it yourself, every invocation sends a fresh request, and the provider charges for it.

Once agents move beyond demos, three pressures show up together and stay for the duration of development:

• Cost – Repeated runs during development burn budget. For a simple agent that exchanges a few hundred tokens per call, this might feel negligible. But development sessions involve dozens of sequential runs, teams have multiple developers iterating in parallel, and the costs compound quickly.
• Latency – Every round trip to the provider stretches the feedback loop. When you are tweaking prompt construction or adjusting response parsing, waiting on a live call each time slows everything down.
• Determinism – The same input does not always produce the same output. That variability makes it harder to isolate whether a difference in behavior came from your code change or from the model.

This is especially visible in teams that build many small, task-specific agents rather than one large agent. Even small per-run costs compound when iteration is constant—and none of that spend actually improves the agent.

What Teams Already Do

Most teams already compensate for this manually. Common patterns include separating development runs from real execution, validating agent wiring before triggering model calls, reusing mocked or previously captured responses, and avoiding live execution early to keep iteration fast.

These approaches work, but they are fragmented. Provider-level caching helps in some cases but is limited. Custom mocks and fixtures are costly to maintain. Replay logic often lives outside the main development flow, and different teams end up solving the same problem with different local tooling.

The problem is not a lack of solutions. It is the lack of a low-friction one that fits naturally into everyday iteration.

What Agent Cache Does

Fiddler Everywhere acts as a proxy that sits between your agent and the remote endpoint. When your agent makes an HTTPS call to, say, api.anthropic.com, Fiddler software intercepts it, forwards it and logs the full request-response pair in the Traffic pane.

The new Agent Calls tab is a focused view inside that pane. It automatically filters and displays HTTPS sessions that target supported model-provider endpoints—such as OpenAI, Anthropic and Gemini—so you are not wading through noise from other traffic. Every captured call gets a Caching toggle.

Enable the toggle, and Fiddler software starts intercepting any outbound call that matches that session’s request. Instead of forwarding the request, it immediately returns the cached response. The endpoint never receives the duplicate call. Your agent sees the exact same payload it would have received from a live call. Token count: zero.

Disable the toggle at any time and live traffic resumes, no restarts required.

How Agent Calls and Caching Behave

A few details that matter when you start using it:

• Deterministic filtering: Sessions appear in Agent Calls automatically when Fiddler software detects traffic to a supported agentic endpoint. You do not need to configure which endpoints to watch.
• First-match caching: If two or more sessions target the same endpoint (for example, https://api.anthropic.com/v1/messages) and both are cached, Fiddler software returns the response from the first cached session.
• No rule interference: Fiddler rules are executed only for non-cached sessions. Cached responses are returned as-is, without rule evaluation.
• Visibility split: After a session is cached, subsequent matching requests appear only in Live Traffic. The Agent Calls tab continues to show the original non-cached captures.

Why It Matters During Development

Agent Cache is built around three practical benefits that matter most during active development.

1. Faster iterations: Replaying a cached response is instant. Instead of waiting on a round trip to the provider on every run, you get a result back immediately—shortening the feedback loop so you can move through prompt and code changes without unnecessary delays.
2. Lower execution costs: Each cached run consumes zero tokens on the provider side. During active development, where the same request may be triggered dozens of times, this directly reduces the token spend that accumulates before a feature is even complete.
3. More predictable behavior: A cached response is fixed and repeatable. Running the same agent logic against the same response on every iteration makes it straightforward to verify that a code change had the intended effect, without having to account for variability in live model output.

Demo: Bug Report Analyzer

To make this tangible, walk through the agent-cache-demo—a minimal Python agent that takes a fixed bug report and returns a structured analysis (severity, category, a plain-English summary and a suggested next step).

The input never changes between runs, which makes it a perfect showcase for Agent Cache: the model’s answer to an identical prompt is always reusable, so there is genuinely no reason to pay for it more than once.

What the Agent Does

The core of agent.py is straightforward:

message = client.messages.create(  
model=MODEL,  
max_tokens=256,  
system=SYSTEM_PROMPT,  
messages=[  
{"role": "user", "content": f"Analyze this bug report:\n\n{report}"}  
],  
)  

It sends the bug report to the Claude API and expects a JSON response like this:

{  
"severity": "high",  
"category": "crash",  
"summary": "App crashes with a NullPointerException when attempting to log in under no network connectivity.",  
"suggested_next_step": "Add a null or connectivity check in NetworkManager.checkConnectivity() before network calls."  
}  

That response is then formatted and printed to the terminal:

── Bug Report Analysis ─────────────────────────────────────  
Severity  : HIGH  
Category  : crash  
Summary  : App crashes with a NullPointerException when attempting to  
log in under no network connectivity.  
Next step : Add a null or connectivity check in  
NetworkManager.checkConnectivity() before network calls.  
─────────────────────────────────────  

Setup

Clone the repository and install dependencies:

git clone [https://github.com/NickIliev/agent-cache-demo](https://github.com/NickIliev/agent-cache-demo)  
cd agent-cache-demo  
  
python -m venv .venv  
source .venv/bin/activate  # macOS / Linux  
.venv\Scripts\activate  # Windows  
  
pip install -r requirements.txt  
export ANTHROPIC_API_KEY=sk-ant-... # macOS / Linux (Git Bash)  
set ANTHROPIC_API_KEY=sk-ant-... # Windows (CMD)  

The demo supports routing traffic through the Fiddler proxy or running directly against the provider. It also covers SSL/TLS trust configuration for HTTPS interception. See the repository README for full details on proxy setup, environment variables and certificate options.

Step 1: The First Live Call

Start Fiddler Everywhere and run the agent:

python agent.py  

The terminal shows the result and, crucially, the token consumption:

[tokens] Input: 312  |  Output: 68  |  Total: 380  

Switch to Fiddler Everywhere and open Traffic > Agent Calls. You will see the captured call to api.anthropic.com with the full request and response visible.

This is your baseline. You paid for 380 tokens. That is fair—you needed the live call to validate the end-to-end flow.

Step 2: Enable the Cache

In the Agent Calls grid, find the captured session and flip its Caching switch to on. That is the entire configuration step.

Step 3: All Subsequent Runs Are Free

Run the agent again:

python agent.py  

The output in the terminal is byte-for-byte identical to the first run, including the token count display. Because the Caching switch was on, Fiddler software served the stored response immediately and never forwarded the request to the provider. The endpoint never saw the call.

You can now iterate on agent.py as many times as you need—refactor the display logic, adjust the JSON parsing, add logging—and none of those runs cost a single token.

When to Use Agent Cache

Agent Cache is a development-stage tool. It is particularly valuable when:

• Iterating on response handling: Your agent already returns a correct response from the model. You are now working on how your code handles that response—formatting, validation, error recovery. None of that work requires fresh model calls.
• Sharing a working state with teammates: Cache a known-good response and share the Fiddler session. Everyone on the team can iterate against the same replay without burning tokens or depending on network access to the provider.
• Working offline or in restricted environments: Once the cache is populated, your agent keeps working even without connectivity to the provider.

Things to Keep in Mind

• Cache matching is request-based. If your agent changes the prompt, the model or any request headers, the cached session will no longer match. Capture and cache the updated variant separately.
• The cache lives in the current Fiddler session. Closing and reopening Fiddler clears the cache state, so the next run after a restart will make a live call. Review cached sessions periodically to keep stored responses aligned with your current workflow.
• Cache is for development, not production. Agent Cache is designed for development workflows where deterministic, repeatable responses are the goal. When you are ready to validate against a live endpoint, disable the cache and resume live calls.

Availability

Agent Cache is available on Fiddler Everywhere Trial, Pro and Enterprise tiers. The feature is not included in Lite licenses.

Try It Yourself

The full demo is on GitHub: github.com/NickIliev/agent-cache-demo. Clone it, set your Anthropic API key, and you can see the before-and-after token counts yourself in under five minutes.

The point is not really the 380 tokens saved in a single run. It is the dozens of runs you make in a typical development session, the parallel runs across a team—all of which can stop paying for answers they already have.

Agent Cache does not change how you build agents. It just removes the tax on iterating.

If you aren’t already using Fiddler Everywhere, it does come with a free trial:

Try Fiddler Everywhere

Leave Feedback

Agent development workflows are still evolving quickly, and your feedback shapes what comes next. If you try Agent Cache during development—or if there is something you wish it did differently—we want to hear about it.

• Email: fiddler-support@progress.com
• GitHub issues: github.com/telerik/fiddler-everywhere/issues
• Demo repository: github.com/NickIliev/agent-cache-demo

Modern applications rely on automation and intelligent processing to handle large volumes of data, and spreadsheets are no exception. With the 2026 Q1 release, Progress introduced Agentic Tools (in Preview) for Telerik Document Processing Libraries (DPL).

These tools are purpose‑built .NET APIs for agentic document workflows, enabling AI agents to analyze, extract, edit and generate Excel and PDF files; run aggregates; transform content; and convert formats directly inside your app. The new Agentic Tools cover both PdfProcessing and SpreadProcessing libraries and are available with a Subscription license.

In this post, we’ll walk you through how to use the SpreadProcessing Agentic Tools to analyze an existing spreadsheet.

Importing the Workbook

Let’s create a simple .NET console app. Our first step is to import the Workbook. I am going to add the necessary DPL dependencies, in this case:

and then use this code:

Workbook workbook = null;

using (Stream input = File.OpenRead("Electric_Vehicle_Population_Data.xlsx"))
{
    XlsxFormatProvider formatProvider = new();
    workbook = formatProvider.Import(input, null);
}

In case you are wondering, this file contains 17 columns and 75,331 rows of data.

An agent using the DPL tools can work with multiple files at the same time by importing and exporting them via the SpreadProcessingFileManagementAgentTools and managing them with the InMemoryWorkbookRepository. However, in this example we are going to concentrate on analyzing one workbook, so we are going to use the SingleWorkbookRepository, a class which gives an agent a single file to work with in memory.

IWorkbookRepository repository = new SingleWorkbookRepository(workbook);

For this code, we need to reference the Telerik.Documents.AI.AgentTools.Spreadsheet package.

Initializing the DPL Agentic Tools

Initializing the Agentic Tools is very simple. For this example, we will use an Azure Open AI deployment, so first we are going to add the Microsoft.Agents.AI.OpenAI and Azure.AI.OpenAI packages. Then we are going to collect the Read and Formula tools in one collection:

List<AITool> tools = new SpreadProcessingReadAgentTools(repository).GetTools().ToList();
tools.AddRange(new SpreadProcessingFormulaAgentTools(repository).GetTools());

And then we can initialize our agent. We are going to need an Azure Open AI endpoint and key and are going to use gpt-4.1-mini.

OpenAI.Chat.ChatClient chatClient = new AzureOpenAIClient(
    new Uri(endpoint),
    new ApiKeyCredential(key))
    .GetChatClient(model);

AIAgent agent = chatClient.AsIChatClient().AsAIAgent(
    instructions: "",
    name: "SpreadsheetAnalyzer",
    tools: tools);

At this point, we can already ask a simple question to check our progress:

AgentResponse response = await agent.RunAsync("What is the value on cell A4?");
Console.WriteLine(response.ToString());

Here is the result:

If you examine the response of the agent more closely, you will notice that it contains three messages. The first is the function call the agent made to the document processing tool GetCellValues and with what parameters. The second is the response. And the third is what the LLM has reasoned and has decided to give us.

Giving It UI

A console app is good for a proof of concept, but it would be nice to give our functionality a more finished look. One of the ways to do this is by using some Progress Telerik for WPF controls. The RadSpreadsheet control can show the content of our file, and we can leverage RadChat for the conversation with the agent.

We can give the repository the Workbook object of the RadSpreadsheet like this when initializing the chat:

IWorkbookRepository repository = new SingleWorkbookRepository(this.radSpreadsheet.Workbook);

Then we are going to subscribe to the SendMessage event, which is where our logic for running the agent is going to go:

this.radChat.SendMessage += this.RadChat_SendMessage;

After a few more tweaks, this is the result:

The full code of the demo can be found on this link: AgentToolsAnalyzeSpreadsheet on GitHub

Conclusion

Agentic workflows introduce a powerful new way to interact with documents, moving beyond static reading and writing to dynamic, intelligent analysis. As you’ve seen, the setup integrates seamlessly with .NET, and, once the agent is initialized, it can leverage the full capabilities of the Document Processing Libraries.

This example is just the beginning! The same approach can be extended to multi-document scenarios, automated reporting, data validation or even generating new spreadsheets from scratch.

The future of document processing is agentic, and it’s already here.

Try out the Telerik Document Processing Libraries, which are included in the Telerik DevCraft bundles to pair perfectly with your favorite component libraries.

Try Telerik DevCraft

Offloading document generation, conversion or manipulation to cloud services allows you to handle large workloads without overloading on-prem resources. Azure Functions and AWS Lambda scale automatically based on demand, so whether you need to generate 10 or 10,000 documents, the infrastructure adjusts dynamically. Serverless models charge per execution time and resources consumed, eliminating the need for dedicated servers for document processing. Thus, you pay only for what you use.

This blog post introduces comprehensive cloud integration demonstrations for Azure and AWS, showcasing PDF processing capabilities using Progress Telerik Document Processing in serverless environments. The examples demonstrate two main integration patterns: PDF merging and external digital signing, implemented for both Azure Functions and AWS Lambda. The complete code projects are available in our SDK repository: Cloud Integration Demos.

Integrate RadPdfProcessing with Azure Functions

First, you’ll need: an active Azure subscription, Azure functions tools installed and the Telerik NuGet feed set up.

1. Create an Azure Functions App

2. Select Anonymous authorization level:

3. Install the following NuGet packages:

• Install the Telerik.Documents.Fixed NuGet package.
• Install the HttpMultipartParser NuGet package:

4. Rename the Functiona1.cs file to “MergeFunction” and introduce your custom implementation in the Run method:

using HttpMultipartParser;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using System.Net;
using Telerik.Windows.Documents.Fixed.FormatProviders.Pdf;
using Telerik.Windows.Documents.Fixed.Model;
 
namespace MyAzureFunctionApp;
 
public class MergeFunction
{
    [Function("MergeFunction")]
    public async Task<HttpResponseData> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req)
    {
        Task<MultipartFormDataParser> parsedFormBody = MultipartFormDataParser.ParseAsync(req.Body);
 
        PdfFormatProvider provider = new PdfFormatProvider();
        RadFixedDocument result = MergePdfs(provider, parsedFormBody.Result.Files);
 
        using (MemoryStream outputStream = new MemoryStream())
        {
            provider.Export(result, outputStream, TimeSpan.FromSeconds(20));
            outputStream.Seek(0, SeekOrigin.Begin);
 
            HttpResponseData httpResponseData = req.CreateResponse(HttpStatusCode.OK);
            httpResponseData.Headers.Add("Content-Type", "application/pdf");
            await outputStream.CopyToAsync(httpResponseData.Body);
 
            return httpResponseData;
        }
    }
 
    static RadFixedDocument MergePdfs(PdfFormatProvider pdfFormatProvider, IReadOnlyList<FilePart> files)
    {
        RadFixedDocument mergedDocument = new RadFixedDocument();
        foreach (FilePart file in files)
        {
            RadFixedDocument documentToMerge = pdfFormatProvider.Import(file.Data, TimeSpan.FromSeconds(20));
            mergedDocument.Merge(documentToMerge);
        }
 
        return mergedDocument;
    }
} 

This Azure Function, named MergeFunction, handles HTTP GET and POST requests to merge multiple PDF files into a single document. It uses:

• HttpMultipartParser to parse multipart form data and extract uploaded files.
• Telerik PdfFormatProvider and RadFixedDocument to import and merge PDF documents.
• The merged PDF is exported to a memory stream and returned as an HTTP response with the application/pdf content type.

The function supports anonymous access and processes uploaded files efficiently, so that the merged PDF is delivered in the response. Since the function is implemented with anonymous access for demo purposes, consider adding authentication as needed for your scenario.

5. Run the project and copy the URL from the window that pops up:

6. Create a .NET Console App (e.g., MyMergeApp) that acts as a client for the Azure Function PDF Merge service.

using System.Diagnostics;
using System.Net.Http.Headers;
 
namespace MyMergeApp
{
    internal class Program
    {
        static void Main(string[] args)
        {
            string functionUrl = "http://localhost:7163/api/MergeFunction";
 
            // Specify PDF files to merge from the Resources directory
            string[] pdfFilePaths = { "../../../Resources/file1.pdf", "../../../Resources/file2.pdf" };
 
            // Create multipart form data content for file upload
            using MultipartFormDataContent content = new();
 
            // Add each PDF file to the form data
            foreach (string filePath in pdfFilePaths)
            {
                byte[] fileBytes = File.ReadAllBytes(filePath);
                ByteArrayContent fileContent = new(fileBytes);
                fileContent.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
                content.Add(fileContent, "files", Path.GetFileName(filePath));
            }
 
            // Send the merge request to the Azure Function
            HttpResponseMessage response = PostAsync(functionUrl, content).Result;
            response.EnsureSuccessStatusCode();
 
            // Read the merged PDF from the response
            byte[] result = response.Content.ReadAsByteArrayAsync().Result;
 
            // Save the merged PDF to disk
            string outputPath = "merged_output.pdf";
            if (File.Exists(outputPath))
            {
                File.Delete(outputPath);
            }
            File.WriteAllBytes(outputPath, result);
 
            // Open the merged PDF in the default viewer
            Process.Start(new ProcessStartInfo(outputPath) { UseShellExecute = true });
        }
        static async Task<HttpResponseMessage> PostAsync(string url, MultipartFormDataContent content)
        {
            using HttpClient httpClient = new HttpClient();
            httpClient.Timeout = TimeSpan.FromMinutes(2); // Allow sufficient time for large files
 
            return await httpClient.PostAsync(url, content);
        }
    }
}

It demonstrates how to send multiple PDF files to the MergeFunction endpoint and handle the merged result. The workflow includes:

• Loading PDF files from a local Resources directory.
• Packaging the files as multipart form data for upload.
• Sending an HTTP POST request to the Azure Function endpoint.
• Receiving the merged PDF in the response and saving it to disk.
• Automatically opening the merged PDF in the system’s default viewer.
  The application uses HttpClient for communication, enables proper content type headers and includes a helper method PostAsync for sending requests with a configurable timeout.

7. Run the Azure Functions .NET Worker (e.g., MyAzureFunctionApp.csproj):

8. While the service is running, run the Console App (e.g., MyMergeApp).

As a result, a merged PDF document will be produced:

Integrate RadPdfProcessing with AWS Lambda

Using an AWS Lambda function for signing PDF documents offers a more secure, scalable and cost-effective approach to digital signature workflows. By offloading the signing process to a serverless environment, sensitive private keys remain isolated in the cloud, reducing the risk of exposure on client machines.

The following tutorial defines the steps for creating an AWS Lambda function that performs digital signature operations for PDF documents using a private key stored in a certificate file. The AWS Lambda function is purposed to act as a more secure service that remotely signs PDF documents, and the private key is never exposed to the client.

Before starting, you’ll need valid AWS Credentials and the Telerik NuGet Feed properly set up.

1. Create AWS Lambda Project (e.g., MyAWSLambda):

2. From the Select Blueprint wizard, select “.NET 8 (Container Image)”:

3. Open the Function.cs file and implement the custom logic for signing PDF documents in the FunctionHandler:

The method receives data to be signed, signs it using a private key certificate, and returns the Base64-encoded signature. The .pfx certificate is stored independently from the project used for processing documents.

NOTE: Do not forget that sensitive data should be stored properly and that this implementation is for demo purposes.

using Amazon.Lambda.Core;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
 
// Assembly attribute to enable the Lambda function's JSON input to be converted into a .NET class.
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
 
namespace MyAWSLambda;
 
public class Function
{
    public async Task<string> FunctionHandler(Input input, ILambdaContext context)
    {
        byte[] dataToSign = Convert.FromBase64String(input.DataToSign);
 
        byte[]? result = SignData(dataToSign, input.DigestAlgorithm);
 
        if (result != null)
        {
            return Convert.ToBase64String(result);
        }
        else
        {
            throw new InvalidOperationException("Signing operation failed");
        }
    }
    static byte[]? SignData(byte[] dataToSign, string? digestAlgorithm)
    {
        string certificateFilePassword = "johndoe";
        string certificateFilePath = "Resources/JohnDoe.pfx";
 
        using (Stream stream = File.OpenRead(certificateFilePath))
        {
            byte[] certRawData = new byte[stream.Length];
            stream.ReadExactly(certRawData, 0, (int)stream.Length);
 
            using (X509Certificate2 fullCert = new X509Certificate2(certRawData, certificateFilePassword))
            {
                using (RSA? rsa = fullCert.GetRSAPrivateKey())
                {
                    if (rsa == null)
                    {
                        throw new InvalidOperationException("Certificate does not contain an RSA private key");
                    }
 
                    // Map the digest algorithm string to HashAlgorithmName
                    HashAlgorithmName algorithmName = HashAlgorithmName.SHA256;
                    algorithmName = digestAlgorithm switch
                    {
                        "Sha384" => HashAlgorithmName.SHA384,
                        "Sha512" => HashAlgorithmName.SHA512,
                        _ => HashAlgorithmName.SHA256,
                    };
 
                    byte[]? bytes = rsa.SignData(dataToSign, algorithmName, RSASignaturePadding.Pkcs1);
                    return bytes;
                }
            }
        }
    }
 
    public class Input
    {
        public string DataToSign { get; set; } = string.Empty;
 
        public string? DigestAlgorithm { get; set; }
    }
}

4. Modify the aws-lambda-tools-defaults.json file and specify the function-name for the AWS Lambda function (e.g., ExternalSignPdfAWSFunction):

{
  "Information": [
    "This file provides default values for the deployment wizard inside Visual Studio and the AWS Lambda commands added to the .NET Core CLI.",
    "To learn more about the Lambda commands with the .NET Core CLI execute the following command at the command line in the project root directory.",
    "dotnet lambda help",
    "All the command line options for the Lambda command can be specified in this file."
  ],
  "profile": "telerik-dpl",
  "region": "eu-north-1",
  "configuration": "Release",
  "package-type": "image",
  "function-memory-size": 512,
  "function-timeout": 30,
  "image-command": "MyAWSLambda::MyAWSLambda.Function::FunctionHandler",
  "docker-host-build-output-dir": "./bin/Release/lambda-publish",
  "function-name": "ExternalSignPdfAWSFunction"
}

5. Create a Console App (e.g., MySigningApp.csproj) that will consume the AWS Lambda function.

6. Install the following NuGet packages:

• AWSSDK.Lambda
• Telerik.Documents.Fixed

The Resources folder stores the unsigned PDF document together with the public .crt certificate.

7. Modify the Program.cs file to demonstrate how to apply a digital signature to a PDF document using the Telerik PdfProcessinglibrary and an external AWS Lambda signer. The workflow includes importing a PDF, creating a signature field with a visual representation, configuring signature settings and exporting the signed document.

Note: We will use the specified function-name in the previous step when creating the LambdaFunctionSigner object:

using System.Diagnostics;
using Telerik.Documents.Fixed.Model.DigitalSignatures;
using Telerik.Documents.Primitives;
using Telerik.Windows.Documents.Fixed.FormatProviders.Pdf;
using Telerik.Windows.Documents.Fixed.Model;
using Telerik.Windows.Documents.Fixed.Model.Annotations;
using Telerik.Windows.Documents.Fixed.Model.DigitalSignatures;
using Telerik.Windows.Documents.Fixed.Model.Editing;
using Telerik.Windows.Documents.Fixed.Model.InteractiveForms;
using Telerik.Windows.Documents.Fixed.Model.Objects;
using Telerik.Windows.Documents.Fixed.Model.Resources;
 
namespace MySigningApp
{
    internal class Program
    {
        static void Main(string[] args)
        {
            PdfFormatProvider provider = new PdfFormatProvider();
            RadFixedDocument document = ImportDocument(provider);
 
            string signatureName = "SampleSignature";
 
            Form form = new Form();
            form.FormSource = new FormSource();
            form.FormSource.Size = new Size(120, 120);
 
            // We will use the editor to fill the Form XObject.  
            FixedContentEditor formEditor = new FixedContentEditor(form.FormSource);
            formEditor.DrawCircle(new Point(50, 50), 20);
            formEditor.DrawText(signatureName);
 
            // The Signature object is added to a signature field, so we can add a visualization to it.  
            SignatureField signatureField = new SignatureField(signatureName);
 
            // Create the external signer that will call AWS Lambda to perform the actual signing
            ExternalSignerBase externalSigner = new LambdaFunctionSigner("ExternalSignPdfAWSFunction", "eu-north-1");
 
            // Configure the signature with digest algorithm and timestamp server
            Signature signature = new Signature(externalSigner);
            signature.Settings.DigestAlgorithm = DigestAlgorithmType.Sha512;
            signature.Settings.TimeStampServer = new TimeStampServer("http://timestamp.digicert.com", TimeSpan.FromSeconds(10));
            signatureField.Signature = signature;
 
            // The widget contains the Form XObject and defines the appearance of the signature field.  
            SignatureWidget widget = signatureField.Widgets.AddWidget();
            widget.Rect = new Rect(200, 600, 100, 100);
            widget.Border = new AnnotationBorder(100, AnnotationBorderStyle.Solid, null);
            widget.Content.NormalContentSource = form.FormSource;
 
            // The Widget class inherits from Annotation. And, as any other annotation, must be added to the respective collection of the page.  
            RadFixedPage page = document.Pages.AddPage();
            page.Annotations.Add(widget);
            document.AcroForm.FormFields.Add(signatureField);
 
            document.AcroForm.SignatureFlags = SignatureFlags.AppendOnly;
 
            ExportDocument(provider, document);
 
        }
 
        static RadFixedDocument ImportDocument(PdfFormatProvider provider)
        {
            using (FileStream stream = File.OpenRead("Resources/SampleDocument.pdf"))
            {
                return provider.Import(stream, TimeSpan.FromSeconds(20));
            }
        }
 
        static void ExportDocument(PdfFormatProvider provider, RadFixedDocument document)
        {
            string outputPath = "ExternallySignedDocument.pdf";
            File.Delete(outputPath);
 
            using (FileStream stream = File.Create(outputPath))
            {
                provider.Export(document, stream, TimeSpan.FromSeconds(60));
            }
 
            Process.Start(new ProcessStartInfo(outputPath) { UseShellExecute = true });
        }
    }
}

8. Implement the External Signer.

The LambdaFunctionSigner class is a custom implementation of an external signer that delegates digital signing operations to an AWS Lambda function. It inherits from ExternalSignerBaseand is designed for scenarios where the private key is securely stored in AWS Lambda, while the public certificate resides locally.

using Amazon.Lambda;
using Amazon.Lambda.Model;
using Amazon.Runtime; 
using System.Security.Cryptography.X509Certificates;
using System.Text;
using System.Text.Json;
using Telerik.Documents.Fixed.Model.DigitalSignatures;
 
namespace MySigningApp
{
    public class LambdaFunctionSigner : ExternalSignerBase
 
    {
        private readonly string functionName;
        private readonly AmazonLambdaClient lambdaClient;
 
        /// <summary>
        /// Creates a new instance of LambdaFunctionSigner.
        /// </summary>
        /// <param name="functionName">The AWS Lambda function name or ARN (e.g., "MyAWSLambda" or "arn:aws:lambda:region:account:function:name")</param>
        /// <param name="region">The AWS region where the Lambda function is deployed (e.g., "us-east-1", "eu-north-1")</param>
        public LambdaFunctionSigner(string functionName, string region)
        {
            this.functionName = functionName;
            var credentials = new BasicAWSCredentials("your-access-key", "your-secret-key");
            this.lambdaClient = new AmazonLambdaClient(credentials, Amazon.RegionEndpoint.GetBySystemName(region));
        }
 
        /// <summary>
        /// Gets the certificate chain used for signing.
        /// </summary>
        /// <returns>An array of X509Certificate2 objects representing the certificate chain.</returns>
        /// <remarks>
        /// The public certificate is loaded from the Resources folder and should match
        /// the private key certificate stored in the AWS Lambda function.
        /// </remarks>
        protected override X509Certificate2[] GetCertificateChain()
        {
            string publicKey = "Resources/JohnDoe.crt";
            return [new X509Certificate2(publicKey)];
        }
 
        /// <summary>
        /// Signs the provided data by invoking the AWS Lambda function.
        /// </summary>
        /// <param name="dataToSign">The byte array containing the data to be signed.</param>
        /// <param name="settings">The signature settings containing digest algorithm and other configuration.</param>
        /// <returns>A byte array containing the digital signature.</returns>
        /// <exception cref="InvalidOperationException">Thrown when the Lambda invocation fails or returns an error.</exception>
        /// <remarks>
        /// This method:
        /// 1. Serializes the data and settings to JSON
        /// 2. Invokes the Lambda function synchronously
        /// 3. Validates the response
        /// 4. Returns the decoded signature bytes
        /// </remarks>
        protected override byte[] SignData(byte[] dataToSign, SignatureSettings settings)
        {
            var requestData = new
            {
                DataToSign = Convert.ToBase64String(dataToSign),
                DigestAlgorithm = settings.DigestAlgorithm.ToString()
            };
 
            string jsonRequest = JsonSerializer.Serialize(requestData, new JsonSerializerOptions
            {
                WriteIndented = true
            });
 
            var invokeRequest = new InvokeRequest
            {
                FunctionName = this.functionName,
                InvocationType = InvocationType.RequestResponse, // synchronous
                Payload = jsonRequest
            };
 
            InvokeResponse invokeResponse = lambdaClient.InvokeAsync(invokeRequest).Result;
 
            if (invokeResponse.StatusCode != 200)
            {
                throw new InvalidOperationException($"Lambda invocation failed with status code: {invokeResponse.StatusCode}");
            }
 
            if (!string.IsNullOrEmpty(invokeResponse.FunctionError))
            {
                string errorMessage = Encoding.UTF8.GetString(invokeResponse.Payload.ToArray());
                throw new InvalidOperationException($"Lambda function error: {invokeResponse.FunctionError}. Details: {errorMessage}");
            }
 
            string jsonResponse = Encoding.UTF8.GetString(invokeResponse.Payload.ToArray());
            string? base64Signature = JsonSerializer.Deserialize<string>(jsonResponse);
 
            if (string.IsNullOrEmpty(base64Signature))
            {
                throw new InvalidOperationException("Invalid response from Lambda function");
            }
 
            return Convert.FromBase64String(base64Signature);
        }
    }
}

9. Run the project.

As a result, the unsigned PDF document is successfully signed:

Wrapping Up

Integrating Telerik Document Processing with Azure Functions and AWS Lambda demonstrates how serverless architectures can transform document workflows. By leveraging cloud scalability and pay-per-use models, organizations can efficiently handle tasks like PDF merging and secure digital signing without maintaining dedicated infrastructure. These approaches not only reduce operational overhead but also enhance security by isolating sensitive keys in the cloud.

As businesses continue to adopt remote and distributed solutions, similar patterns can be extended to other workflows such as document conversion, watermarking and batch processing, unlocking even greater flexibility and cost efficiency. The examples provided serve as a foundation for building robust, cloud-powered document services that scale seamlessly with demand.

Try out the Telerik Document Processing Libraries, which are included in the Telerik DevCraft bundles to pair perfectly with your favorite component libraries.

At its core, the Telerik and Kendo UI 2025 Q4 release is about giving developers, team leads and enterprises a partner they can trust: AI tools that understand the Telerik and Kendo UI libraries inside-out, adapt to their technology stack and meet the standards of enterprise-ready UI application development. These tools don’t ask teams to start from scratch. They’re simply designed to accelerate what you’re already building.

The spotlight of this 2025 Q4 release is the Telerik Agentic UI Generator—a new way to build UI with speed and confidence. Developers can now prompt their way into fully functional pages—complete with layouts, styling, accessibility, needed components and data bindings. It does this from an MCP server that works in any AI-enabled IDE.

The Telerik Agentic UI Generator debuts in Telerik UI for Blazor, KendoReact and Kendo UI for Angular as part of DevCraft Complete or Ultimate subscriptions. The Agentic UI Generator is an evolution of the AI Coding Assistants currently available across all major Telerik and Kendo UI libraries, reporting and document processing tools, giving developers a full productivity stack.

Beyond development acceleration, the 2025 Q4 release empowers teams to continue embedding AI directly into their applications. New and enhanced AI components like the Inline AI Prompt, AI-optimized Chat UI and prompt-driven Data Grid bring natural language control to everyday user scenarios.

AI-driven innovation only delivers value when it’s matched with stability and long-term platform confidence. That’s why Progress continues the tradition of day-zero compatibility with Microsoft’s latest technologies with .NET 10 fully supported at launch.

The 2025 Q4 release introduces AI-driven debugging capabilities in Fiddler Everywhere, too, expanding Progress’ MCP ecosystem beyond UI development. With Fiddler MCP integration, network traffic analysis and debugging data are available directly inside your IDE. Combined with the new Debugging Assistant, Fiddler transforms the debugging journey into a guided, conversational experience that helps resolve issues faster and earlier in the development cycle.

To see the new updates firsthand, don’t forget to sign up for the release webinars:

• Telerik 2025 Q4 Release Webinar: Web, Desktop and Mobile on Dec 3
• Kendo UI 2025 Q4 Release Webinaron Dec 4
• Telerik Reporting and Fiddler 2025 Q4 Release Webinar on Dec 5

Let’s Dive into the 2025 Q4 Highlights

Build and Deliver Faster with Context-Aware AI

• Telerik Agentic UI Generator: Generate pages as quickly as possible with Telerik Agentic UI Generator. Use prompts to assemble layouts, grids, forms and styles based on Telerik and Kendo UI components. Keep your IDE and workflow and code at least 30% faster.
• IDE-integrated AI Coding Assistants: Combined with the Agentic UI Generator, the AI Coding Assistants, currently available across all major Telerik and Kendo UI libraries, deliver context-aware, specialized code so teams can ship faster and do more.
• Prompt-controlled Data Grid: Empower users to effortlessly interact with the Data Grids using natural language, whether through the built-in prompt interface or a unified, app-wide chat experience.
• New Inline AI Prompt: Ideal for enabling in-context interactions such as rewriting content, fixing errors and generating alternatives.
• AI-enhanced Chat UI: This component is redesigned to enable smarter, more natural interactions through streaming responses, text-to-speech, flexible response formats and built-in token tracking.
• Redesigned AI Prompt: All key web UI libraries feature an enhanced AI Prompt that supports a new message template, speech-to-text and streaming buttons, improved accessibility and more.
• Enhanced GenAI-powered report insights: Local embeddings for more conscious, controlled spending and tighter data privacy. Plus, broader viewer support, including WPF Viewer (remote engine), Native Blazor Viewer and Native Angular Viewer now fully supporting GenAI insights.
• Conversational prompts in Progress ThemeBuilder: Refine the AI-generated theme through natural, conversational feedback. Adjust colors, spacing, typography and accessibility in plain language, and see instant updates.
• MCP debugging: With Fiddler MCP integration, network traffic analysis and debugging data are available directly inside your IDE, enabling developers to quickly pinpoint performance bottlenecks, security issues or failed sessions.
• AI demo hub: The new dedicated AI demo hub, showcasing AI-enhanced components and features is available across Telerik and Kendo UI web products.

Embrace Next-Gen Frameworks

• Day-zero support for .NET 10: Continuing day-zero support for Microsoft’s newest frameworks, all Telerik products now feature compatibility with .NET 10.

Streamline Development with New, Interactive Components

• Diagram in Telerik UI for Blazor and Kendo UI for Angular: Map relationships, workflows and structures with customizable shapes, flexible connections and built-in layouts with the new Diagram.
• Chat UI in Telerik UI for Blazor: Elevate user engagement with modern, real-time conversations, connecting people or enabling intelligent interactions through AI-powered chatbots.
• Kendo UI for Angular Form: Easily build and organize complex forms with a structured, configurable layout. Group inputs, dropdowns, labels, hints, error messages and more to deliver clear, consistent and user-friendly forms.
• Speech-To-Text Button: Empower users to convert speech into text with a single click, making it easy to add voice input to forms, search bars, chat interfaces and other interactive scenarios.
• Bottom Sheet and Skeleton controls in Telerik UI for .NET MAUI: Slide up additional content from the bottom of the screen to enhance your app experience with the BottomSheet control. Create a preview of how content is going to be displayed before it is loaded with the Skeleton component.

Unlock Robust Features in Your Favorite Components and Tools

• Stacked data layout mode in Data Grids: Deliver a consistent, user-friendly experience across devices with an adaptive, card-like display optimized for both desktop and mobile.
• Workflow diagram in Telerik UI for ASP.NET Core/MVC and Kendo UI for jQuery: Specialized shape types allow you to represent algorithms, tasks and events. While these shapes are tailored for workflows, they’re versatile enough for any diagram scenario.
• PDF Viewer enhancements: Text highlight, free text annotations and form filling for completing PDF forms directly within your app are added to Kendo UI for Angular. Form filling is also available in Telerik UI for Blazor. AI-powered PDF querying and summarization are now present in Telerik UI for WPF and UI for WinForms.
• Responsive Form layout in Angular and React: Build forms that automatically adapt their columns, spacing and field arrangements across breakpoints to deliver a seamless user experience on any screen size.
• Dark mode in Progress ThemeBuilder: Switch to the new dark mode for a more comfortable experience in lowlight setups.
• Document Processing Libraries (DPL) improvements: DPL continues to expand its AI and file-processing capabilities, giving developers more flexibility and smarter ways to work with documents.
• Debugging Assistant: Fiddler transforms the debugging journey into a guided, conversational experience that helps resolve issues faster and earlier in the development cycle.

What’s New & Release History

To see everything that is new in 2025 Q4, visit the What’s New in Telerik and Kendo UI page. For a deeper dive into each product, follow the links below.

With the recent releases, Progress is helping to shape a new era of developer productivity: AI that behaves less like a tool and more like a teammate. Instead of forcing developers to change their flow to match an AI system, Telerik, Kendo UI and Fiddler delivered AI tools that bring intelligence directly into your environment, components and patterns.

Whether generating full UI layouts, refining code in the moment, debugging network traffic or enabling end users to trigger smart actions through prompt-driven interfaces, these products move beyond traditional AI integration into the realm of agentic, embedded collaboration.

At its core, the 2025 Q4 release on November 19 is about giving developers, team leads and enterprises a partner they can trust: AI tools that understand Telerik and Kendo UI inside-out, adapt to their technology stack and meet the standards of enterprise-ready UI application development. These tools don’t ask teams to start from scratch. They’re simply designed to accelerate what you’re already building.

The flagship innovation of this 2025 Q4 release is the Telerik Agentic UI Generator*—a new way to build UI with speed and confidence. Developers can now prompt their way into fully functional pages—complete with layouts, styling, accessibility, needed components and data bindings. It does this from an MCP server that works in any AI-enabled IDE.

* The Telerik Agentic UI Generator debuts in Telerik UI for Blazor, KendoReact and Kendo UI for Angular as part of DevCraft Complete or Ultimate subscriptions.

The Agentic UI Generator is an evolution of the AI Coding Assistants currently available across all major Telerik and Kendo UI libraries, reporting and document processing tools, giving developers a full productivity stack. Developers using the early versions of the AI Coding Assistants have reported an average of 30% time savings, and this innovation should go even further.

Beyond development acceleration, the 2025 Q4 release empowers teams to continue embedding AI directly into their applications. New and enhanced AI components like the Inline AI Prompt, AI-optimized Chat UI and prompt-driven Data Grid bring natural language control to everyday user scenarios. Instead of clicking through multiple panels or configuring complex filters manually, users can simply ask: “Show me all orders processed last month” or “Highlight anything above threshold.” This is not AI for novelty; it’s AI applied with purpose, enhancing the way both developers and end users interact with applications built on Telerik and Kendo UI.

AI-driven innovation only delivers value when it’s matched with stability and long-term platform confidence. That’s why Progress continues the tradition of day-zero compatibility with Microsoft’s latest technologies with .NET 10 fully supported at launch.

Rounding out the productivity story, the 2025 Q4 release introduces AI-driven debugging capabilities in Fiddler Everywhere, expanding Progress’ MCP ecosystem beyond UI development. With Fiddler MCP integration, network traffic analysis and debugging data are available directly inside your IDE, enabling developers to quickly pinpoint performance bottlenecks, security issues or failed sessions. Combined with the new Debugging Assistant, Fiddler transforms the debugging journey into a guided, conversational experience that helps resolve issues faster and earlier in the development cycle.

Save Your Seat for the Webinars!

Find out what’s new in your favorite UI component libraries, reporting and debugging tools by joining our webinars!

Find the details and specific per product highlights in the webinar pages linked below. You can register for more than one webinar.

Progress Telerik .NET Web, Desktop and Mobile 2025 Q4 Release Webinar | December 3

Discover all updates across Telerik UI for Blazor, UI for ASP.NET Core, UI for ASP.NET MVC, UI for ASP.NET AJAX, UI for WPF, UI for WinForms, UI for .NET MAUI and ThemeBuilder. Tune in 11:00 a.m.–1:00 p.m. ET on Wednesday, June 3.

Save Your Seat

Progress Kendo UI 2025 Q4 Release Webinar | December 4

Discover all updates across KendoReact and Kendo UI for Angular, Vue and jQuery, as well as ThemeBuilder. Tune in 11:00 a.m.–1:00 p.m. ET on Thursday, December 4.

Save Your Seat

Progress Telerik Reporting and Fiddler 2025 Q4 Release Webinar | December 5

Discover all updates across Telerik Reporting, Report Server and Fiddler Everywhere. Tune in 11:00 a.m.–1:00 p.m. ET Friday, December 5.

Save Your Seat

And the Best Part About the Release Webinars?

The live webinars are a great opportunity for you to ask questions of the team. We’ll be waiting to hear from you on X—just use the #heyTelerik and #heyKendoUI hashtags before and during the webinars.

Sign up today to make sure you don’t miss these great events with our experienced developer advocates and experts:

• Ed Charbeneau, Microsoft MVP, international speaker, writer, online influencer, Developer Advocate with a passion for .NET
• Alyssa Nicoll, Google Developer Expert and Angular Developer Advocate
• Kathryn Grayson Nanz, Developer Advocate with a passion for React, UI and design
• Rick Hellwege, Principal Sales Engineer, reporting guru and innovator with a passion for experimenting with the latest technologies and frameworks

Can’t wait to see you soon!

Rate limiting is a technique that verifies clients consume the server’s resources responsibly. It is essential for preventing malicious actors from abusing resources. This technique monitors each client’s requests to API endpoints. If their requests exceed a particular limit—that is, breach a particular constraint within a time frame—the client is either blocked or their request is delayed, slowed down or silently ignored.

NestJS is a popular framework that makes it easy for developers to build enterprise-grade server-side applications and provides them with a suite of tools to solve common problems.

In this article, we will be exploring the package for rate limiting. We will first explore rate limiting and some of its core concepts and see how this tool can be used to solve common rate limiting problems in our NestJS applications. We will explore some interesting challenges when implementing rate limiting in real-world applications and examine configurations that this package provides to help us counter those problems.

Prerequisites

This guide assumes the reader is familiar with TypeScript, backend development using Node.js, and HTTP and RESTful APIs.

Project Setup

Assuming you have the Nest CLI installed, let’s now set up a NestJS project by running the following command:

nest new rate-limiting

The application is created in a folder called rate-limiting. Feel free to pick a folder name of your choice.

Next, let’s install @nestjs/throttler, which is the rate limiting package for NestJS.

cd rate-limiting
npm install @nestjs/throttler

How Rate Limiting Works

Now, let’s briefly describe how rate limiting works and highlight some of the core concepts powering it. Understanding this section will be important when we start using the @nestjs/throttler package.

• The resource owner defines the constraint on what is allowed—that is, the limit. Limits are time-bound. The time frame a limit is applied to is called a window, and limits are expressed as “limit per window” (e.g., five requests per second, one job per hour, etc.).
• The resource owner then tracks the client’s requests to access their resources. Tracking can be done based on some identifier (e.g., an ID of some database entity, the client’s IP address, etc.). Tracking is a stateful operation, so the resource owner implements some storage mechanism to hold tracking information for clients. The storage containers to hold this information could be databases or in-memory storage.
• If the client exceeds the defined limit, the resource owner responds either by blocking the request for some duration and returning a 429 response code or by throttling the request (i.e., ignoring or slowing down the response to the user’s request).
• The resource owner implements a rate limiting algorithm to make everything work. Common rate limiting algorithms include token bucket, leaky bucket, fixed window and sliding window algorithms.

Examples of rate limiting in real-world applications include the following:

• A payment gateway may limit requests from clients trying to get the status of a transaction to, for example, one request per minute.
• A cloud service like EAS limits users with free tier accounts to only create 30 builds for their mobile applications per month, with a concurrency limit of one.
• A media manipulation service like Cloudinary constrains API consumers on a free account to upload a limited number of files in each request, with each file not exceeding a particular size.

The @nestjs/throttler Module

Let’s now explore the contents of the rate limiting module we will be using:

• It provides an abstraction over all the complexity involved in rate limiting and provides us with a simple interface to set up only the rate limiting options we need, while it handles the rest.
• It provides a wide range of options that allow us to configure limits, handle client tracking, storage, etc.
• It is storage agnostic, so it allows us to optionally configure different storage mechanisms for tracking. By default, tracking is done using an in-memory store using the JS Map data structure. It also supports regular databases—the most popular option here is Redis, as we will see later.
• If the client exceeds the defined limit, this module responds by blocking the client.
• Although this guide will explore how it can be used in a RESTful API, it is also compatible with GraphQL and WebSockets.

Setting up Some Routes

Normally, a web server will contain one or more endpoints. Let us define a few. Update your app.controller.ts file with the following:

import { Controller, Get } from "@nestjs/common";
@Controller("app")
export class AppController {
  @Get("/a")
  getA(): string {
    return "this is A";
  }
  @Get("/b")
  getB(): string {
    return "this is B";
  }
  @Get("/b")
  getC(): string {
    return "this is C";
  }
}

We defined three routes: /app/a, /app/b and /app/c. Verify that AppController is mounted in the app.module.ts file as shown below:

import { Module } from "@nestjs/common";
import { AppController } from "./app.controller";
@Module({
  imports: [],
  controllers: [AppController],
  providers: [],
})
export class AppModule {}

Add Rate Limiting to the Entire App

Update the app.module.ts file to look like this:

import { Module } from "@nestjs/common";
import { AppService } from "./app.service";
import {
  minutes,
  seconds,
  ThrottlerGuard,
  ThrottlerModule,
} from "@nestjs/throttler";
import { APP_GUARD } from "@nestjs/core";
import { AppController } from "./app.controller";
@Module({
  imports: [
    ThrottlerModule.forRoot({
      throttlers: [
        {
          name: "first",
          ttl: 1000,
          limit: 1,
          blockDuration: 1000,
        },
        {
          name: "second",
          ttl: seconds(10), // 10000
          limit: 5,
          blockDuration: seconds(5),
        },
        {
          name: "third",
          ttl: minutes(1), // 60000
          limit: 25,
        },
      ],
      errorMessage: "too many requests!",
    }),
  ],
  controllers: [AppController],
  providers: [
    AppService,
    {
      provide: APP_GUARD,
      useClass: ThrottlerGuard,
    },
  ],
})
export class AppModule {}

The ThrottleModule enables us to define the rate limiting options in our app. Using either its forRoot() or forRootAsync() overloaded methods, we pass an object defining the options we want. The most important property is one called throttlers—it holds an array of objects, each representing the rate limiting options we want. We can declare as many as required. In our case, we specified three of them.

Each throttle option has properties, but the only mandatory ones are limit and ttl (time to live). However, we added some other interesting ones, which we will look at in a bit.

We can read the first entry in the options array like so: The client is limited to 1 (limit) request per 1000ms (TTL), and if they exceed that, they will be blocked for 1000ms (blockDuration) during which the server responds with a 429. You can apply this model to read the remaining options.

While there are many other optional options (six others at the point of writing), we only used two: blockDuration and name. The former is quite intuitive; if not specified, it defaults to the TTL value. Note that time is always specified in milliseconds when using this module.

The name property defines a name for the group. If not specified, it resolves to the string default. This property helps during tracking to distinguish how tracking information will be stored across options.

We can also add options to define how we want to generate identifiers to track clients or whether, for some option groups, we may want to skip some routes in our app.

Now, for the root object, we also included another optional property called errorMessage, which accepts a string or a function that resolves to the message that will be sent when the user exceeds any of the defined limits.

Finally, we need to verify our entire application is guarded using the rate limiting options, so we used the special APP_GUARD injection token to provision the ThrottlerGuard class. The ThrottlerGuard class is where all the magic happens. It is responsible for tracking and maintaining the state for clients and blocking them when necessary.

To test our running application, open the terminal and start the server by running the following command:

npm run start:dev

Using a browser’s address bar or any API testing platform, let’s proceed to test our API. In this article, we will be using Progress Telerik Fiddler Everywhere. Notice that whenever we exceed any of the limits, we get a 429 response as shown below.

How Tracking Works

Tracking information is stored in a map using key-value pairs. A hyphen (-) separates the pieces that make up the tracking keys. The tracking key is derived from the name of the controller, the handling function, the name of the throttle option and a custom client identifier. By default, this is the client’s IP address.

The diagram above shows the key in plain text, but internally they are hashed (SHA256) before they are used as keys.

The tracking data is derived from the throttle options. It maintains relevant information such as:

• How many requests the client made
• The time for each limit
• The block duration and status

Notice that there are three instances of the tracking keys and their corresponding tracking information maintained for each endpoint for each client, since we defined three different options.

Overriding Rate Limiting Options for Certain Routes

Update your app.controller.ts file to match the following:

import { Controller, Get } from "@nestjs/common";
import { Throttle } from "@nestjs/throttler";
@Controller("app")
export class AppController {
  @Throttle({
    first: {
      ttl: 3000,
      limit: 1,
      blockDuration: 10000,
    },
  })
  @Get("/a")
  getA(): string {
    return "this is A";
  }
  @Get("/b")
  getB(): string {
    return "this is B";
  }
  @Get("/b")
  getC(): string {
    return "this is C";
  }
}

Depending on what your application needs, it is often better to change the rate-limiting options either on one endpoint (i.e., at the route level) or a group of endpoints (i.e., at the controller level). Regardless of which, the @nestjs/throttler module provides us with the handy Throttle decorator to do so.

This function expects an object whose keys are the throttle option name attributes configured earlier in the forRoot method of the ThrottlerModule. The values are just overrides of the previous options.

In our case, we reconfigured the option called first and we limited it to one request every three seconds, with a block duration of 10 seconds.

Now if we try to hit /app/a more than once in three seconds, we get an error. Also note that second and third settings will still apply to this endpoint.

Partly or Completely Disabling Rate Limiting for One or More Routes

Not all parts of an application will need rate limiting. Update your app.controller.ts file with the following:

import { Controller, Get } from "@nestjs/common";
import { SkipThrottle, Throttle } from "@nestjs/throttler";
@Controller("app")
export class AppController {
  //...
  @SkipThrottle({
    first: true,
    second: true,
  })
  @Get("/b")
  getB(): string {
    return "this is B";
  }
  //...
}

The SkipThrottle decorator allows us to disable rate limiting again, either on the controller or route level. It expects an object whose keys are the names of throttle options and whose values are booleans. For example, in our case we disabled first and second throttle options on the /app/b endpoint. This means only the rate limiting option named third will apply to this route.

Rate Limiting Problems in Real World Applications

In this section, we will look at some common rate limiting problems we encounter in real-world applications and how we can solve them. Our solutions will use the @nestjs/throttler module and some of the features provided by the Nest framework:

• Tracking clients by IP address when our web server is behind a reverse proxy
• Storing client tracking information across multiple instances

Tracking Clients by IP Address When Our Web Server Is Behind a Reverse Proxy

It has already been established that the @nestjs/throttler module allows us to track users based on different identifiers, but by default it does so using the client’s IP, which is the most common option.

There are some interesting things to note here: When we deploy our server-side applications, in most cases, we don’t allow direct client communication with them. Rather, we usually place our server behind another web server (e.g., Nginx, Apache, Caddy, Traefik, etc.) which serves as a load balancer and/or reverse proxy. Load balancers provide many benefits when paired with our web server, such as security from attackers, caching, compression, traffic distribution, etc.

Each time the client makes a request, it goes through the reverse proxy and then to our actual NestJS server. To verify our NestJS server knows about the client’s IP where the request originated from, we need to check that the load balancer sends this information to it. When using a load balancer like Nginx, by default this information is not sent. This means our NestJS server treats the request as if it originated from Nginx, and this is not what we want.

For our demo let’s create a docker-compose.yaml file in the project’s root and add the following to it:

services:
  backend1:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    expose:
      # used to expose port to other containers
      - 3000
    volumes:
      - ./src:/app/src
      - /app/node_modules
    command: npm run start:dev
    hostname: backend1
    container_name: backend1
  nginx:
    image: nginx
    depends_on:
      - backend1
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

We set up two services: the first being our NestJS web server called backend1, which has a hostname of backend1 and exposes port 3000 to other containers. The other is Nginx, the load balancer we will be using, that is exposed on our machine on localhost:8080. We created an nginx.conf file in our project root. We defined a bind mount to override the contents of the one that ships with the Nginx container.

This file looks like so:

worker_processes 1;

events {
    worker_connections 1024;
}
http {
    include mime.types;
    upstream backend_cluster {
        # round robin algorithm is used by default
        server backend1:3000;
    }
    server {
        listen 80;
        server_name localhost;
        location / {
            # Proxy requests to the upstream we called backend_cluster
            proxy_pass http://backend_cluster;
            # Pass the X-Forwarded-For header
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Client-Ip $remote_addr;

            proxy_set_header Host $host;
        }
    }
}

We will focus on the more important blocks in this file:

The proxy_pass directive proxies requests from the load balancer to our backend cluster named backend_cluster in the upstream block. The upstream block for now has one entry that points to our NestJS server (i.e., “backend1:3000”).

To forward the client IP address, we used two custom headers to show two different ways we can do this. The first is a random header we called X-Client-IP and the other is the more popular X-Forwarded-For header, which we are more interested in. Both of them will set the client’s IP, which is stored in the $remote_addr variable. $proxy_add_x_forwarded_for uses this internally and appends the client’s IP to whatever was set in the X-Forwarded-For that came with the original request.

The Host header verifies that the upstream (i.e., our NestJS server) receives the right URL so that the right controller attends to the request.

Using a Custom Header

If you prefer using the custom header, we can just directly extend the ThrottlerGuard and override its getTracker() method as shown below.

Let’s update our app.module.ts file with the following:

// Add this
@Injectable()
export class ThrottlerBehindProxyGuard extends ThrottlerGuard {
  protected async getTracker(req: Record<string, any>): Promise<string> {
    return req.headers["x-client-ip"];
  }
}

@Module({
  imports: [
    ThrottlerModule.forRoot({
      throttlers: [
        //...throttlers
      ],
      errorMessage: "too many requests!",
    }),
  ],
  controllers: [AppController],
  providers: [
    AppService,
    {
      provide: APP_GUARD,
      useClass: ThrottlerBehindProxyGuard,
    },
  ],
})
export class AppModule {}

In the code above, we retrieved the client’s IP from the custom header set.

Using the X-Forwarded-For Custom Header

We can directly read the contents of the X-Forwarded-For header from the request object, like we did previously with our random X-Client-IP header. However, this header is a somewhat de facto header used by most proxy servers (e.g., Nginx in our case) to forward the client’s IP to the web server behind it.

This header is already known to ExpressJS, so we just need to do a few things to enable the Express APIs to parse it for us automatically.

Let’s now tweak our backend code to parse this value. Update your main.ts file with the following:

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { NestExpressApplication } from "@nestjs/platform-express";
import { Injectable, ExecutionContext, CallHandler } from "@nestjs/common";

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  app.set("trust proxy", true);
  await app.listen(3000);
}
bootstrap();

NestJS allows us to choose between Express or Fastify, and we are going to use the former.

By setting the trust proxy setting on the Express API, it automatically tells Express to trust the X-Forwarded-For header and parse it to an array, storing it in the request object in its ips array (i.e., req.ips).

It then picks the leftmost entry in this array and stores it in req.ip. To put it in more context: assuming the X-Forwarded-For holds “a b c” (assuming there were two hops before the request reached our web server, where a, b and c are IP addresses), req.ips will hold [a, b, c] and req.ip holds a, where a is the client’s IP address.

By default, since the @nestjs/throttler module relies on the req.ip property for tracking, everything works automatically just by using the trust proxy setting without having to extend the ThrottlerGuard class like we did to manually extract the contents of our X-Client-IP header for @nestjs/throttler.

Storing Client Tracking Information Across Multiple Instances

Another great thing about having our web server behind a load balancer is that it allows us to run multiple instances of the web server while the load balancer distributes incoming traffic across all instances. This is important for throughput, availability and proper resource utilization.

In the context of rate limiting, this also presents some storage concerns. First, by default, since the @nestjs/throttler module uses an in-memory store (a JavaScript Map data structure, to be specific), to remember tracking information for rate limiting, this means when we have multiple instances of our app, each instance maintains its own in-memory store, as shown below.

This storage decentralization presents a problem (i.e., assuming we have three instances, a, b and c, it is possible for a client to be blocked on one of the servers, e.g., a, and still be able to access b and c).

So we need to centralize the storage location for the tracking information and move to a structure that looks like the one below.

The @nestjs/throttler module allows us to provide our storage option if we want, provided it implements the ThrottlerStorage interface. We won’t be creating ours; instead, we will use a community-provided package that allows us to use Redis as the persistence layer.

Let’s install this module in our app. Run the following command in your terminal:

npm install --save @nest-lab/throttler-storage-redis ioredis

Next, let us update our docker-compose.yaml file to set up Redis, and then make three instances of our web server in our file:

services:
  backend1:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    ports:
      - "3002:3000"
    expose:
      - 3000
    environment:
      INSTANCE_NAME: BACKEND_1
    volumes:
      - ./src:/app/src
      - /app/node_modules
    command: npm run start:dev
    hostname: backend1
    container_name: backend1
  backend2:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    ports:
      - "3003:3000"
    expose:
      - 3000
    environment:
      INSTANCE_NAME: BACKEND_2
    volumes:
      - ./src:/app/src
      - /app/node_modules
    command: npm run start:dev
    hostname: backend2
    container_name: backend2
  backend3:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    ports:
      - "3004:3004"
    expose:
      - 3000
    environment:
      INSTANCE_NAME: BACKEND_3
    volumes:
      - ./src:/app/src
      - /app/node_modules
    command: npm run start:dev
    hostname: backend3
    container_name: backend3
  nginx:
    #... nginx service
  redis:
    image: redis/redis-stack
    environment:
      REDIS_ARGS: "--requirepass 1234"
      REDISSEARCH_ARGS: "--requirepass 1234"
      REDIS_HOST: redis
      REDIS_USERNAME: default
      REDIS_PASSWORD: 1234
      REDIS_DATABASE_NAME: 0
      REDIS_PORT: 8001
    volumes:
      - ./local-data/:/data
    ports:
      - "6379:6379"
      - "8001:8001"

Notice we included an environment variable for each instance called INSTANCE_NAME. This will be used later so we know which instance of our web server is handling the proxied request.

Let’s update our upstream block in our nginx.conf file to include the two other server instances, making them 3:

worker_processes 1;

events {
    worker_connections 1024;
    #
}
http {
    # ensures that the server includes the proper mimetypes when the response is sent back to the client
    include mime.types;
    upstream backend_cluster {
        # Define the backend servers using round-robin
        server backend1:3000;
        server backend2:3000;
        server backend3:3000;
    }
    server {
        # server block
        }
    }
}

Before we start our fleet of services, we need to do a few things. Let’s start by updating the app.module.ts file to use the Redis storage module:

import { Module } from "@nestjs/common";
import { AppService } from "./app.service";
import {
  minutes,
  seconds,
  ThrottlerGuard,
  ThrottlerModule,
} from "@nestjs/throttler";
import { APP_GUARD } from "@nestjs/core";
import { AppController } from "./app.controller";
// throttler-behind-proxy.guard.ts
import { Injectable } from "@nestjs/common";
import { ThrottlerStorageRedisService } from "@nest-lab/throttler-storage-redis";

@Module({
  imports: [
    ThrottlerModule.forRoot({
      throttlers: [
        // {
        //   name: 'first',
        //   ttl: 1000,
        //   limit: 1,
        //   blockDuration: 1000,
        // },
        {
          name: "second",
          ttl: seconds(10), // 10000
          limit: 4,
        },
        // {
        //   name: 'third',
        //   ttl: minutes(1), // 60000
        //   limit: 25,
        // },
      ],
      errorMessage: "too many requests! on " + process.env.INSTANCE_NAME,
      storage: new ThrottlerStorageRedisService(
        `redis://default:1234@host.docker.internal:6379/0`
      ),
    }),
  ],
  controllers: [AppController],
  providers: [
    AppService,
    {
      provide: APP_GUARD,
      useClass: ThrottlerGuard,
    },
  ],
})
export class AppModule {}

We included a connection string to connect to Redis. The username and password fields are hardcoded here; they match those specified in the REDIS_ARGS: --requirepass 1234 and the REDIS_USERNAME default in our docker-compose.yaml file.

Also, we temporarily disabled all the other throttle options except the one named second. For now, the user is limited to four requests every 10 seconds and will be blocked for 10 seconds if they exceed the limit.

We also modified the error message to include the INSTANCE_NAME environment variable to know which instance the client is blocked on.

So that we know which server responds when we hit each endpoint, let’s now update our app.controller.ts file:

import { Controller, Get } from "@nestjs/common";
import { SkipThrottle, Throttle } from "@nestjs/throttler";
@Controller("app")
export class AppController {
  // @Throttle({
  //   first: {
  //     ttl: 3000,
  //     limit: 1,
  //     blockDuration: 10000,
  //   },
  // })
  @Get("/a")
  getA(): string {
    return "this is A on " + process.env.INSTANCE_NAME;
  }
  // @SkipThrottle({
  //   first: true,
  //   second: true,
  // })
  @Get("/b")
  getB(): string {
    return "this is B on " + process.env.INSTANCE_NAME;
  }
  @Get("/b")
  getC(): string {
    return "this is C on " + process.env.INSTANCE_NAME;
  }
}

We appended the INSTANCE_NAME environment variable to each endpoint response string to know which of our backend instances is responding to our request.

Let’s rebuild our images and restart our fleet of services again by running:

docker compose up -d --build

Now, when we hit our reverse proxy at localhost:8080/app/a:

Based on our throttle options definition, we defined limits that restrict the client to four requests every 10 seconds, and will be blocked for 10 seconds if they exceed the limit. Notice in the image above that when the limit is exceeded, the client is blocked across all instances.

Conclusion

Rate limiting helps force clients to consume resources responsibly. This guide shows us how we can use this technique to secure our web server and its resources from abuse.

As part of our mission to empower developers with intelligent, productivity-focused tooling, Progress is expanding the reach of Telerik and Kendo UI AI Coding Assistants with the 2025 Q3 release.

Previously available for Telerik UI for Blazor and KendoReact, the AI Coding Assistants are now trained on and available across all major UI libraries, including Kendo UI for Angular, Telerik UI for ASP.NET Core, UI for WPF, UI for WinForms and UI for .NET MAUI, and, for the first time, extended to developer productivity tools like Telerik Reporting and Document Processing.

Don’t forget to save your seat for the upcoming webinar, “Developer Productivity Unlocked: How to Harness AI, Agents and Automation for Better Workflows” on Sept. 3, 2025, at 11 am ET.

Save Your Seat Today

Along with the IDE-integrated AI Coding Assistants, Progress is also introducing new AI capabilities in Progress ThemeBuilder, our popular visual styling app, for creating and customizing themes using conversational prompts, saving time otherwise spent manually editing properties and configuring CSS. A series of other AI-powered components and features are also part of this extensive release, along with lots more.

Let’s Dive Into the 2025 Q3 Highlights

Fast and Smart AI-Assisted App Development

• AI Coding Assistants across all key UI libraries: Unlike standalone AI solutions, Telerik and Kendo UI AI Coding Assistants—now available in Kendo UI for Angular, Telerik UI for ASP.NET Core, UI for WPF, UI for WinForms, UI for .NET MAUI, Telerik Reporting and Document Processing—integrate into the tools developers already use. These assistants don’t replace AI-powered tools, they enhance them, bringing deep knowledge of Telerik and Kendo UI component libraries and tools directly into the development process. Whether building UI, embedding reports or automating document workflows, the AI Assistants deliver context-aware, specialized code so teams can ship faster and do more.

• Conversational prompts in Progress ThemeBuilder: You can now refine the AI-generated theme through natural, conversational feedback. Adjust colors, spacing, typography and accessibility in plain language—and see instant updates.

• New Inline AI Prompt control: Available in Kendo UI for Angular, UI for jQuery, KendoReact, Telerik UI for Blazor, UI for ASP.NET Core and MVC, the Inline AI Prompt control is ideal for enabling in-context interactions such as rewriting content, fixing errors and generating alternatives.

• AI-enhanced Conversational UI (Chat) across all web UI libraries: The component is now redesigned to enable smarter, more natural interactions through streaming responses, text-to-speech, flexible response formats and built-in token tracking.

• Redesigned AI Prompt: All major web UI libraries now feature an enhanced AI Prompt component that supports a new message template, speech-to-text and streaming buttons, improved accessibility and more.

• AI-powered (smart) Data Grids: The robust Data Grid component across all Kendo UI libraries and Telerik UI for Blazor is now enriched with prompt-based Data Grid actions for sorting, grouping, filtering and row highlighting. In addition, a new AI Assistant column is ready to deliver contextual summaries, explanations and warnings directly from row-level data.

• Enhanced GenAI-powered Reporting insights: Gain smarter, more precise insights with fine-tuned tokenization control in Telerik Reporting, reducing input requirements while delivering higher-quality, actionable report results.

Beyond Comprehensive UI Libraries: More Components in the Spotlight

• Speech-To-Text Button across all major UI libraries: Empower users to convert speech into text with a single click, making it easy to add voice input to forms, search bars, chat interfaces and other interactive scenarios.

• New Diagram in Kendo UI for Angular and Telerik UI for Blazor: Quickly visualize relationships, workflows and structures with built-in layouts, customizable shapes and flexible connections.

• New Conversational UI (Chat) in Telerik UI for Blazor: Bring modern, real-time conversations right into your Blazor apps. Connect users with each other or facilitate interactions with intelligent virtual assistants like AI-driven chatbots.

• Form component now in Kendo UI for Angular: Easily build and organize complex forms with a structured, configurable layout. Group inputs, dropdowns, labels, hints, error messages, and more to deliver clear, consistent and user-friendly forms in your Angular apps.

• New BottomSheet control in Telerik UI for .NET MAUI: Slide up additional content from the bottom of the screen to enhance your app experience. Use it to display complementary information, surface contextual actions or offer secondary navigation options.

• One-Time-Password (OTP) Input control now in Telerik UI for ASP.NET AJAX: Already available in Kendo UI for Angular, UI for jQuery, Telerik UI for ASP.NET Core and MVC, the OTP Input control in Telerik UI for ASP.NET AJAX enhances application security.

Robust Features, Adaptiveness and Support for the Latest Technologies

• Stacked data layout mode in Telerik and Kendo UI Data Grids: Deliver a consistent, user-friendly experience across devices with an adaptive, card-like display optimized for both desktop and mobile.

• Workflow diagram in Kendo UI for jQuery: Specialized shape types allow you to represent algorithms, tasks and events. While these shapes are tailored for workflows, they’re versatile enough for any diagram scenario.

• PDF Viewer enhancements: Text highlight and free text annotations are now supported in Kendo UI for Angular, while form filling is available in Telerik UI for Blazor, allowing users to complete PDF forms directly within your Blazor application.

• Responsive Form layout in Kendo UI for Angular and KendoReact: Build forms that automatically adapt their columns, spacing and field arrangements across breakpoints to deliver a seamless user experience on any screen size.

• Dark Mode in Progress ThemeBuilder: Switch to the new Dark mode for a more comfortable experience in lowlight setups.

• Compatibility with .NET 10 previews: Telerik products are now compatible with .NET 10 Preview 6, so you’re ready for the future of .NET development.

• Multiple Telerik Reporting and Report Server enhancements: Telerik Reporting project templates now use SDK-style notation, while the Standalone Report Designer features improved support for coded reports. A white-labeling feature is added to Telerik Report Server for .NET, enabling full customization.

• Document Processing Libraries (DPL) improvements: The WordsProcessing library now offers AI-powered querying and summarization. Meanwhile, PdfProcessing introduces full accessibility and standards-compliant PDF generation.

• Fiddler Everywhere latest updates: Our robust debugging tool now shows streaming responses in real time in the body inspectors, plus groups multiple error messages into a single notification for better user experience.

What’s New & Release History

To see everything that is new in 2025 Q3, visit the What’s New in Telerik and Kendo UI Products page. For a deeper dive into each product, follow the links below.

Creating web APIs is part of most developers’ routines these days. In this sense, it is worth reflecting on how this process can be accelerated to increase productivity and improve performance without sacrificing organization and maintainability. It was with this in mind that the concept of “fast endpoints” emerged.

In this post, we will understand what fast endpoints are, how to implement them in practice and see what advantages they can offer compared to the traditional use of Controllers in ASP.NET Core and the modern minimal APIs.

⚡️Understanding Fast Endpoints

The concept of fast endpoints is related to approaches that seek to simplify and accelerate the development of APIs, with a focus on performance, low coupling between components and better code organization.

Fast endpoints emerged as an alternative to the traditional approaches for handling requests in web APIs, such as ASP.NET MVC Controllers and Minimal APIs, seeking to combine performance, organization and simplicity in a single model.

Fast Endpoints in ASP.NET Core

In ASP.NET Core, we have access to fast endpoints through the library of the same name, available at https://fast-endpoints.com. It operates under the MIT license, which means it is open source and can be used in private and commercial projects.

In addition, it follows the Request-Endpoint-Response (REPR) design pattern, which advocates the clear organization of an API’s components, separation of responsibilities, and ease of maintenance and reading.

Before the arrival of fast endpoints, the main ways to create web APIs were through traditional Controllers and modern Minimal APIs. Although both are excellent approaches, they have some gaps:

Controllers: Although they are robust, organized and ready for practically any type of configuration, they can be excessively verbose for simple scenarios. The way of implementing a Controller using classes and attributes often generates unnecessary overhead for lean APIs, and in some cases, it can make it difficult to have a more resource-oriented approach and a clear separation of responsibilities.

Minimal APIs: On the other hand, Minimal APIs offer a much simpler way to create endpoints, ideal for small and fast services. However, as they grow, they can compromise the organization and maintainability of the code. The lack of clear conventions and the mixture of business logic with route definition can make the code difficult to scale and test.

It is precisely in these limitations that fast endpoints stand out as a middle ground between these two approaches. They combine the best of both worlds:

• Performance and simplicity of Minimal APIs, with direct routing and a lean structure (the documentation indicates that the performance is on par with Minimal APIs and is noticeably better than MVC controllers)
• ️Organization, testability and separation of responsibilities of Controllers, allowing the use of validation, filters, dependency injection and clean encapsulation through specialized classes per endpoint

The great advantage of fast endpoints is that they allow you to write clean, modular and performant code without sacrificing clarity and scalability. This makes them an excellent choice for modern applications that require both agility and a solid foundation for long-term maintenance.

️Fast Endpoints in Practice

Now that we have seen what fast endpoints are and what their advantages are compared to traditional approaches, let’s create an ASP.NET Core application to implement them in practice.

As a scenario, let’s imagine that you need to create an activity logging system for the development team. This system must be simple, performant and at the same time support validations without being complex. In this case, we can use fast endpoints to create an API that fits these requirements.

To keep the focus on the main topic, some implementation details will not be shown in this post, but you can check the complete code in this GitHub repository: Work Log - source code.

To create the base application, you can use the command below. This post uses version 9 of .NET, which is currently the latest stable version.

dotnet new web -o WorkLog

Then, to install the NuGet packages used in this example, you can use the following commands:

dotnet add package FastEndpoints
dotnet add package FluentValidation
dotnet add package FastEndpoints.Validation

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet add package Microsoft.EntityFrameworkCore.Tools

The next step is to create the model class, so create a new folder called “Models” and, inside it, add the class below:

namespace WorkLog.Models;
public class TimeEntry
{
    public Guid Id { get; set; }
    public string UserName { get; set; } = default!;
    public string? ProjectName { get; set; }
    public DateTime Date { get; set; }
    public decimal Hours { get; set; }
    public string? Description { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}

The DbContext class will be used to set the database configurations, so create a new folder called “Data” and, inside it, add the following class:

using Microsoft.EntityFrameworkCore;
using WorkLog.Models;

namespace WorkLog.Data;
public class WorkLogDbContext : DbContext
{
    public DbSet<TimeEntry> TimeEntries { get; set; }
    public WorkLogDbContext(DbContextOptions<WorkLogDbContext> options) : base(options) { }
}

Creating the Endpoints

The endpoint classes will contain the fast endpoints functionalities. For this, they will implement the Endpoint class from the FastEndpoints NuGet package. The first endpoint will be used to create new records in the database and then retrieve it, for this we will create some auxiliary classes for request and response. So, create a new folder called “Request” and inside it add the class below:

namespace WorkLog.Requests;
public class CreateTimeEntryRequest
{
    public string? UserName { get; set; }
    public string? ProjectName { get; set; }
    public DateTime Date { get; set; }
    public decimal Hours { get; set; }
    public string? Description { get; set; }
}

Then, create a new folder called “Response” and add the following classes to it:

• CreateTimeEntryResponse

namespace WorkLog.Responses;
public class CreateTimeEntryResponse
{
    public Guid Id { get; set; }
    public string? UserName { get; set; }
    public string? ProjectName { get; set; }
    public DateTime Date { get; set; }
    public decimal Hours { get; set; }
    public string? Description { get; set; }
    public DateTime CreatedAt { get; set; }
}

• GetTimeEntryResponse

namespace WorkLog.Responses;
public class GetTimeEntryResponse
{
    public Guid Id { get; set; }
    public string? UserName { get; set; }
    public string? ProjectName { get; set; }
    public DateTime Date { get; set; }
    public decimal Hours { get; set; }
    public string Description { get; set; } = default!;
    public DateTime CreatedAt { get; set; }
}

Finally, let’s create the endpoint class. Create a folder called “Endpoints” and, inside it, add the following class:

using FastEndpoints;
using WorkLog.Data;
using WorkLog.Models;
using WorkLog.Requests;
using WorkLog.Responses;

namespace WorkLog.Endpoints;
public class CreateTimeEntryEndpoint : Endpoint<CreateTimeEntryRequest, CreateTimeEntryResponse>
{
    private readonly WorkLogDbContext _dbContext;

    public CreateTimeEntryEndpoint(WorkLogDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public override void Configure()
    {
        Post("/time-entries");
        AllowAnonymous();
        Summary(s =>
        {
            s.Summary = "Create a new time entry";
            s.Description = "Registers hours worked by a professional on a specific project.";
        });
    }

    public override async Task HandleAsync(CreateTimeEntryRequest req, CancellationToken ct)
    {
        var timeEntry = new TimeEntry
        {
            Id = Guid.NewGuid(),
            UserName = req?.UserName,
            ProjectName = req?.ProjectName,
            Date = req.Date,
            Hours = req.Hours,
            Description = req.Description,
            CreatedAt = DateTime.UtcNow
        };

        _dbContext.TimeEntries.Add(timeEntry);
        await _dbContext.SaveChangesAsync(ct);

        await SendAsync(new CreateTimeEntryResponse
        {
            Id = timeEntry.Id,
            UserName = timeEntry.UserName,
            ProjectName = timeEntry.ProjectName,
            Date = timeEntry.Date,
            Hours = timeEntry.Hours,
            Description = timeEntry.Description,
            CreatedAt = timeEntry.CreatedAt
        });
    }
}

Note that the CreateTimeEntryEndpoint class represents an HTTP endpoint responsible for creating a new record of hours worked by a professional on a project.

The class inherits from Endpoint<CreateTimeEntryRequest, CreateTimeEntryResponse>, defining the input and output contract of this endpoint.

The Configure() method defines the main settings of the endpoint. We specify that it responds to HTTP POST requests on the /time-entries route and allows anonymous access (without authentication). We also use the Summary() method to document the purpose of the endpoint, making it easier to generate automatic documentation and for other developers to read.

The most important part is the HandleAsync method. When a request is received, we create a new instance of TimeEntry, filling its fields with the data from the request. This new record is then added to the context and persisted in the database with SaveChangesAsync.

Finally, we send a response to the client with the newly created timer data, encapsulated in the CreateTimeEntryResponse.

Then, still within the Endpoints folder, add the following class, which represents the endpoint for data recovery:

using FastEndpoints;
using Microsoft.EntityFrameworkCore;
using WorkLog.Data;
using WorkLog.Responses;
namespace WorkLog.Endpoints;

public class GetTimeEntriesEndpoint : EndpointWithoutRequest<List<GetTimeEntryResponse>>
{
    private readonly WorkLogDbContext _db;

    public GetTimeEntriesEndpoint(WorkLogDbContext db)
    {
        _db = db;
    }

    public override void Configure()
    {
        Get("/time-entries");
        AllowAnonymous();
    }

    public override async Task HandleAsync(CancellationToken ct)
    {
        var entries = await _db.TimeEntries
            .Select(e => new GetTimeEntryResponse
            {
                Id = e.Id,
                UserName = e.UserName,
                ProjectName = e.ProjectName,
                Date = e.Date,
                Hours = e.Hours,
                Description = e.Description,
                CreatedAt = e.CreatedAt
            })
            .ToListAsync(ct);

        await SendAsync(entries);
    }
}

This separation between input, entity and response models keeps the application more robust, decoupled and ready to evolve. In addition, this structure provides clear reading, reduces the boilerplate common in REST APIs, and offers a more fluid experience for both the writer and the maintainer of the code.

Creating the Validators

FastEndpoints has integration with the FluentValidations package, which means we can perform validations without much effort. So, to configure the validations of our API, create a new folder called “Validators” and, inside it, add the class below:

using FastEndpoints;
using FluentValidation;
using WorkLog.Requests;

namespace WorkLog.Validators;
public class CreateTimeEntryValidator : Validator<CreateTimeEntryRequest>
{
    public CreateTimeEntryValidator()
    {
        RuleFor(x => x.UserName).NotEmpty();
        RuleFor(x => x.ProjectName).NotEmpty();
        RuleFor(x => x.Date).NotEmpty().LessThanOrEqualTo(DateTime.Today);
        RuleFor(x => x.Hours).GreaterThan(0).LessThanOrEqualTo(24);
    }
}

Here, we create a validation class to check the input data of the record creation request. Note that the class inherits from Validator, which is a class from the FastEndpoints namespace. In addition, it implements validation methods such as NotEmpty(), which belongs to FluentValidation. This way, we have separate and organized validations for each endpoint.

The last thing to do is add the necessary settings for the classes created previously to the Program class. So, replace the Program class code with the code below:

using FastEndpoints;
using Microsoft.EntityFrameworkCore;
using WorkLog.Data;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<WorkLogDbContext>(options =>
    options.UseSqlite(builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddFastEndpoints();

var app = builder.Build();

app.UseFastEndpoints();

app.Run();

Here, in addition to configuring the WorkLogDbContext database class, we also added the FastEndpoints configuration through the methods builder.Services.AddFastEndpoints() and app.UseFastEndpoints().

Note how the Program class is clean and organized, without the presence of endpoints, as happens when we use the Minimal APIs approach. Now we can reserve the Program class only for configurations, which is its main function .

Running the Fast Endpoints

Now that the implementations are ready, we can test if the endpoints are working correctly. To do this, we will use Progress Telerik Fiddler Everywhere to execute the requests and check the responses.

First, we will execute the HTTP-POST route: http://localhost:5011/time-entries to save a new record. This example will use the following JSON:

{
    "userName": "John Davis",
    "projectName": "john.davis@example.com",
    "date": "2025-08-01",
    "hours": 6.5,
    "description": "Worked on implementing the user authentication flow and fixed bugs related to token refresh."
}

The response in Fiddler returned a status of 200 – OK, which means that the endpoint worked correctly.

Now, let’s run the same endpoint, but this time without sending the required parameters to check if the FluentValidation validations are working. This time, the following JSON will be sent in the request body:

{
    "userName": "",
    "projectName": "",
    "date": "2025-08-01",
    "hours": 6.5,
    "description": "Worked on implementing the user authentication flow and fixed bugs related to token refresh."
}

Now, as expected, the response was an error indicating that some fields are mandatory.

Finally, we will make a request that will use the GetTimeEntriesEndpoint to retrieve the previously inserted record. So, executing the HTTP route: GET - http://localhost:5011/time-entries, we will have the following result:

Conclusion

FastEndpoints offers a modern and versatile way to build APIs in ASP.NET Core, combining the performance and simplicity of minimal APIs with the controller framework. This balanced approach improves maintainability and facilitates scalability and testability.

In this post, we explore its main advantages and create a sample API using the NuGet package, highlighting how its endpoint-centric design results in cleaner code.

If you are looking for an alternative to traditional API patterns, FastEndpoints is worth exploring. In addition to the features covered in this post, there are others, such as validation, filters and testability, that will probably help you in your projects.

While the various report designers in Progress Telerik Reporting will let you do magical things, in the end, your report is saved as a TRDP file (essentially an XML document) that describes your report declaratively and, potentially, served from your organization’s Report Server (which I’ve assumed in this post).

But Telerik reports are also inherently interactive. You can, for example, in any of the Report Designers, create a report that allows the user to pick the data they want to see (either by explicitly selecting a filter in the report’s UI or by selecting items displayed in the report). And, with the Report Designer, you do that declaratively, without code, using drag-and-drop and setting report options.

But the next step in interactive reports is to have your report interact with the page that’s hosting the report. That interaction can take two forms by having the:

• Page hosting the report respond as the user interacts with the form
• Report respond as the user interacts with the host page

While implementing either of these interactions does require code, you start the process off declaratively.

Setting Up

For this post, I’m using this combination of HTML and JavaScript to set up a:

• HTML div element to hold a report
• HTML style element with CSS attributes to control the report’s appearance
• JavaScript reference to the div element id
• A JavaScript function (called loadReport) that displays a modified version of one of the sample reports that comes with the Telerik Report Server

That all looks like this:

<div id="dashboard">
    loading...
</div>

<style>
      #dashboard {
          position: absolute;
          left: 5px;
          right: 5px;
          top: 5px;
          bottom: 5px;
          overflow: hidden;
          font-family: Verdana, Arial;
      }
  </style>

<script>
const dashboardDiv = $("#dashboard");

const loadReport = () => {
     dashboardDiv.telerik_ReportViewer({
         reportServer: {
             url: "http://...",
             username: "…",
             password: "…"
         },
         reportSource: {
             report: "Samples/Dashboard"
         }
     });
};
</script>

As my loadReport function shows, loading a report is essentially declarative. To display the report in the selected div element, you pass a JavaScript object literal declaring all the information that the Telerik Report Viewer needs to a telerik_ReportView function tied to the div element.

With that loadReport function in place, I can call that function in my page’s jQuery ready event to load the report. Once the report is loaded, I capture a global reference to the report:

let rv;

$(() => {
    loadReport();
    rv = dashboardDiv.data("telerik_ReportViewer");
}

I’m using the Dashboard report as my case study because it provides an opportunity for adding interactivity: In the Dashboard report, a user can select a year from the list on the right side of the report and have that year displayed in the main body of the report on the left:

Capturing Report Events

To have your application’s host page react as the user interacts with the report that the page is displaying, you need to wire up a JavaScript function to a Report Viewer event. The Telerik Report Viewer provides more than a dozen events.

I’m going to use the updateUi event, which fires whenever the report’s UI changes (and picking a new year does change the report’s UI). To tie a function to an event, you declare the event in the JavaScript object literal that defines your report and then tie your function to that event.

Tying a function to the updateUi event looks like this:

reportSource: {
  report: "Samples/Dashboard"
},
updateUi: e => {

}

The updateUi event might not be the best choice for your application. If, for example, you wanted to be able to cancel the change (perhaps after validating the user’s input), you might prefer using the interactiveActionExecuting event which supports canceling user changes which updateUi event does not.

If you start wiring up more than one event in your report’s declaration (or if the function for an event gets large), then it can make your object literal hard to read. If so, you can define your function outside the object literal and just tie the function name to the event in your report’s object literal, like this:

const handleYearChange = e => {

    }
};

const loadReport = () => {
    dashboardDiv.telerik_ReportViewer(
     {
        reportServer: {
            url: "http://...",
            username: "…",
            password: "…"
        },
        reportSource: {
            report: "Samples/Dashboard"
        },
        updateUi: handleYearChange
     }
  );
};

If you want your event to be available some of the time, you can bind events dynamically by their names using the Report Viewer’s bind and unbind methods, passing the name of the event (slightly altered) and the function you want to bind to the event. This code binds and then immediately unbinds my handleYearChange function, for example:

rv.bind(telerikReportViewer.Events.UPDATE_UI, handleYearChange);
rv.unbind(telerikReportViewer.Events.UPDATE_UI, handleYearChange);

Writing Host Page Code

Now that I’ve tied the JavaScript function to the report’s event, I can access the report through the global reference I created after the report was loaded. Alternatively, inside the function, you can use the e parameter that’s passed to the function to access the report (it’s in the e parameter’s data.sender property):

const handleYearChange = e => {
    let rv = e.data.sender;
}

With that reference, I can now extend my handleYearChange function to update my host page and have my host page respond to the user’s changes to my report. For this case study, I’ll just display in a textbox in my host page the year that the user has selected in the report.

I’ll do the easy part first and add that textbox, setting its id attribute to currentYear and then create a JavaScript global reference to the textbox:

    <input id="currentYear" />

const curInput = $("#currentYear");

The Report Viewer object model has, in addition to the events, a set of methods that return objects that you can use to manage the report. The Report Viewer ReportSource method, for example, returns an object with exactly one property, called parameters. That parameters property, in turn, exposes an object that has a named property for each parameter defined in the report (you’ll have to get the name of your parameter by opening the report in one of the Report Designers).

In my sample report, the parameter holding the currently selected year is called ReportYear and I can use that parameter to retrieve the year that the report is currently displaying.

One caveat: You want to exercise some care in the function that you tie to the updateUi event because the event is raised repeatedly as a page is loaded—once each for the page’s sections (header, body, footer, etc). Letting your code execute multiple times can lead to subtle bugs (we won’t ask how I know this).

Here’s the code in my updateUi event to grab the ReportYear parameter’s value and stuff it into my textbox (but do it only once, when the parameter changes):

let currentYear;

updateUi: (e) => {
    parms = rv.reportSource().parameters;
    if (currentYear !== parms.ReportYear) {
        currentYear = parms.ReportYear;
        curInput.val(parms.ReportYear);
    }
}

Now, whenever the user selects a year in the report, the textbox on the report’s host page will be updated.

Interacting with the Report

As I said at the start, interactivity goes two ways. When the user interacts with the report’s host page, you might want to have the report respond to that change. In my case study, I might want the report to display the data for a year that the user types into the textbox on my host page.

Implementing that requires setting the appropriate parameter on the report (ReportYear, in my case) from the user’s input (my CurrentYear textbox) and refreshing the report. To do that, I extend my textbox’s declaration to call a function when the user changes the contents of the textbox and exits the textbox:

    <input id="currentYear" onchange="updateReport()" />

In this new updateReport function, I need to retrieve the current value from the textbox, update the appropriate parameter on the report (ReportYear, in my case), and call the report’s refreshReport method—still using the global reference to the report that I created after the report was loaded. That code looks like this:

let UpdateReport = () => {
    let parms = rv.reportSource().parameters;
    parms.ReportYear = curInput.val();
    rv.refreshReport();
};

Now, as the user interacts with my host page, my report will respond.

Obviously, these are very simple examples, but the Report Viewer has more methods than the ReportSource method that I’ve used. But what you have here is the basic structure of any kind of integration you’ll want to add, regardless of what you want to do.

Telerik Reporting comes with your favorite framework UI component library when you bundle with Progress Telerik DevCraft. And this all comes with a 30-day free trial. So, go on:

Try Now

As my friends, family, coworkers and probably several people on the internet already know: I am a AI skeptic—and I’m not particularly shy about it, either. I’m not really sold on the productivity improvement angle, and I’m especially cautious (and critical) when it comes to using it to create content. I’m routinely underwhelmed by emails, blogs, illustrations, logos and more that were clearly created without human involvement. As an artist and writer myself, those aren’t things that I, personally, am seeking to replace or automate out in my own life.

That said, I also work in tech where AI is (for the time being) borderline inescapable. I also think it’s decidedly lame to write something off without giving it a genuine try. And, if I’m completely honest, I was also just plain curious: what was everyone else seeing in this that I wasn’t? Was there some trick or approach to using it that I just hadn’t mastered yet? I created a ChatGPT account, started using the CoPilot account work had provided for us, installed our Kendo UI AI Coding Assistant and committed to giving “this AI thing” a real, honest shot for an extended period of time. I’ve been using it for the last couple months, and … well, my opinions are mixed.

There are some places where AI tooling excels and was genuinely helpful. There were many places where it wasn’t suited to what I was asking it to do, and I spent more time fighting with the machine than getting anything actually done. Ultimately, I’m not sold on AI as the do-everything tool it’s often marketed as—however, there are a handful of things it was great at that I have folded into my regular routine. With all that being said, here are the places and ways where I’m using AI (as a certified AI skeptic).

Where I Use AI

Pair Programming

I found (pretty darn quickly) that I do not like when an AI tool writes the code for me: by which I mean literally populating or auto-completing lines of code in my IDE. Vibe coding and I simply do not get along; I found it challenging to follow what was being written, I didn’t remember how I had structured or named things (because I hadn’t actually structured or named them), and it ultimately slowed me down significantly.

What I did find helpful was using the AI like a pair programming partner. My coworker Alyssa wrote about this a while ago, and it was part of what informed my approach and helped me find a middle ground that worked for me. In the past, if I was implementing something new, I’d try and find examples in the docs or a tutorial blog that walked me through it—and I’d almost always have to make some adjustments for it to work in the context of my own project. Now, it’s handy to ask the AI to generate my own step-by-step implementation tutorials, all customized to my exact tech stack and needs.

I also really like using it to replace looking stuff up in the docs. The Progress Kendo UI AI Coding Assistant is particularly useful here—believe it or not, even though I’m the KendoReact Developer Advocate, I don’t actually have every possible prop for all 120+ components memorized yet (I know, I know, I’m working on it). Being able to throw a quick syntax question into the chat sidebar in VS Code is super handy. I’m not a fan of having it write the whole app for me—although it can do that—but it does have a much better “memory” than I do for whether that prop is called theme or themeColor (spoiler: it’s themeColor).

Of course, I’d also be remiss if I didn’t mention using AI for troubleshooting errors in my code—it’s saved me more than a few times, now. However, (like all troubleshooting) the trick here is to not fall down the rabbit hole. It’s shockingly easy to just ask it question after question, following the natural chain it creates and letting it suggest wilder and wilder approaches. By the time you’ve tried 4-5 things it’s suggested with no solution, you’re on the AI version of the 10th page of Google: the answer just isn’t going to be here. In the pre-AI days, I would always suggest to junior devs to set a time limit on their troubleshooting: if you’ve tried for 1-2 hours (max) and made no headway, it’s time to stop Stack Overflow-ing and call in another person. Although the tech is different now, I think the rule still stands; time box your AI query-ing and learn to identify when you’ve hit the point of diminishing returns.

To-do Lists and Scheduling

One of the places where I have actually found AI to live up to the productivity hype is to do a braindump of all my tasks and goals at the beginning of each week and let it make a little schedule for me.

I’ll tell it my pre-existing obligations on each day (calls, appointments, etc.), personal to-dos (workouts, chores, social engagements), school assignments (when I was still finishing up my grad school work) and work tasks and ask it to make a structured to-do list for each day of the week. It’s good at grouping mentally similar tasks, reducing the amount of “code switching” you need to do, and it’s also helpful to me to see where I have time set aside for each thing. I was never a time-blocking kind of person; it was just too specific and I always felt like I wasted more time setting up the schedule vs. actually completing the work. Outsourcing that work to the AI has been beneficial, and my Monday mornings now usually start with a schedule dump into ChatGPT.

Body Doubling (Kind Of)

This one is (admittedly) a little embarrassing, but for the sake of honesty I’m going to include it: I like to tell the AI chatbot when I start and finish tasks. I think of it kind of like body doubling, but without having to bother another actual person or actually sync up work schedules. I know we’ve moved into full-on placebo effect here, but something about knowing I have to “report back” when I’ve finished helps keep me on task. Brains are weird.

Summarizing My Own Writing

As I mentioned above, I don’t like to have the AI create content for me—that includes writing, which I do a lot of in my role. Conference talks, videos, blogs, ebooks: I spend a lot of time click-clacking away on my little keyboard, and I’m not terribly keen to outsource that work. Where I have found AI to be helpful in my writing process is to have it read my work and then ask it questions. What was the primary message the author was communicating in this piece? What were the main steps of this tutorial? What was the author’s tone?

Rather than having it check my work for accuracy (it’s decidedly not good at that) or rewrite my words, I like to have it summarize my work back to me so I can make sure I hit all the points I intended to hit and emphasized the right stuff. After all, someone else is probably going to be doing that—even if it’s not as direct as I’m doing here, they’ll be reading the Google AI summary of it or asking a question that some AI will reference my work to answer. It’s a helpful way to confirm that my most important messages are being effectively communicated when I write.

Where I Avoid AI

Writing

Yes, I know I just talked about this a little bit. But even beyond doing literal content creation, I also avoid AI generating outlines or overviews, emails, conference talk descriptions, DMs, etc. It’s just too opinionated, and it has a distinct tone of voice that doesn’t match my own. Plus, I know how I feel when I get an email or read a piece of work that wasn’t written by a human—and it feels bad. If it wasn’t important enough for you to write, then it’s not important enough for me to read.

Image Generation

Look guys, it’s just not good. Maybe it will be good in the future, but that future is not today. It’s always riddled with little mistakes, images that are supposed to look “real” have that kind of soft-edged glazed-over look, and just forget trying to generate anything with text in it. Websites like Unsplash offer high-quality, royalty-free images—just use those.

Research

Until AI can say “I can’t find that,” then I’ll never trust it for research—it will just hallucinate an answer and present it to you like the truth. That goes for everything from actual academic paper research to “what time does this restaurant open?” I’m simply not interested in spending my time fact-checking a machine. I even switched away from Google because the (inaccurate) AI summaries at the top drove me crazy. Until AI chatbots are capable of admitting that they can’t do something, I’ll be DuckDuckGo-ing my questions (even though that doesn’t exactly roll off the tongue the way Google-ing did).

Vibe Coding

As detailed above. I could maybe see doing it for a small, one-off side project—but if it’s anything you’re going to have to work with again at literally any point in the future, it’s just not worth it. And even for that small, one-off thing, you’re more likely to learn and retain what you’ve worked with better if you write the code yourself.

How Are You Using AI?

Where have these tools fit into your life? Are you calling on them every day, or just a couple times a week? We’re all still finding our balance as AI tooling works its way into … well, just about everything. I’m not a believer in throwing the baby out with the bathwater, so I’ll keep playing with the new stuff as it comes out. After all, this isn’t an all-or-nothing game: take what works and leave the rest!

Have you ever imagined having a complete history of data in a distributed application? With Event Sourcing, each change becomes an immutable event, for full traceability in ASP.NET Core.

Event Sourcing is an architectural pattern widely used in large and medium-sized systems due to its versatility in dealing with complexities through an approach different from traditional approaches: Instead of saving the current state, it records each change in the system as an event.

In this post, we will understand how Event Sourcing works and what its advantages are compared to traditional approaches. We will also implement an ASP.NET Core application using the principles of Event Sourcing.

Understanding Event Sourcing

Event Sourcing is an architectural pattern that aims to handle changes through immutable events, storing the complete history of all changes made to a system, allowing the reconstruction of the state at any time.

Imagine a bank account management platform. Instead of having an Account entity, which has a balance that is updated with each new transaction, in Event Sourcing, each transaction (deposit, withdrawal, transfer) is recorded as an event that does not change. Each event is recorded exactly as it was sent, so the current account balance is derived from the amounts deposited and withdrawn in previous events. This allows tracking the entire history of account movements, so all information from the first change to the last is present.

The image below demonstrates how movements in a bank account are handled using the traditional and Event Sourcing approaches.

Advantages of Using Events

The use of events brings several advantages, especially in systems that need to maintain traceability (history) and be scalable and resilient. Below are some of the main aspects that make the use of events a great choice:

Complete data history: The use of events allows you to have an immutable history of everything that happened. This facilitates audits, debugging and analysis of the behavior of the system during its life cycle.

Reproduction and reconstruction of the state: It is possible to reconstruct the current state of any entity, simply by reapplying past events.

Scalability and performance: The use of events allows the separation between writing (events) and reading (projections), allowing optimizations for each one in a specific way. In addition, systems can be designed to scale horizontally, since events are stored asynchronously.

Easy asynchronous integration: Allows the creation of decoupled microservices, where services react to events without the need for direct calls.

Resilience and fault tolerance: In case of failure, simply reprocess the events to restore the system state. In addition, there is no risk of data loss, as events are stored immutably and are always available.

Implementing Event Sourcing in ASP.NET Core

Now we will implement an ASP.NET Core application that uses the Event Sourcing pattern to send and receive deposit and withdrawal events. For this, we will use two libraries: RabbitMQ and MassTransit.

RabbitMQ is a message broker that implements the Advanced Message Queuing Protocol (AMQP). It acts as an intermediary between message producers and consumers, allowing them to communicate in a decoupled and asynchronous way.

MassTransit is a .NET library for asynchronous messaging. It simplifies integration with message brokers like RabbitMQ or Azure Service by abstracting away complex details and supporting messaging patterns like publish/subscribe, request/response and saga orchestration.

Prerequisites

Below are some prerequisites that you need to meet to reproduce the tutorial in the post.

1. .NET version – You will need the latest version of .NET (.NET 9 or higher)
2. Docker – Required to run the local RabbitMQ service

Creating the Application and Installing the Dependencies

To create the application, you can use the command below:

dotnet new web -o BankStream

Then, in the project root, you can use the following commands to install the NuGet packages:

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package MassTransit
dotnet add package MassTransit.RabbitMQ
dotnet add package MassTransit.AspNetCore

Creating the Events

Now let’s create the entities that represent the deposit and withdrawal events. They will be simple, as the focus is to demonstrate the sending and consumption of the events.

So, create a new folder called “Events” and, inside it, create the following records:

• DepositEvent

namespace BankStream.Events;

public record DepositEvent(Guid Id, string AccountId, decimal Amount);

• WithdrawalEvent

namespace BankStream.Events;

public record WithdrawalEvent(Guid Id, string AccountId, decimal Amount);

Creating the Consumers

Then, let’s create the consumers. They are responsible for receiving the events and processing the actions related to it. In this case, update the status and register it in the database.

First, let’s create the classes and enums used by the consumers. So, create a new folder called “Models” and, inside it, create the following classes:

• StatusEnum

namespace BankStream.Models;
public enum StatusEnum
{
    Pending,
    Completed,
    Failed,
    Canceled,
    Reversed,
    InProgress,
    OnHold
}

• TransactionTypeEnum

namespace BankStream.Models;

public enum TransactionTypeEnum
{
    Deposit,
    Withdrawal
}

• TransactionStatus

namespace BankStream.Models;

public class TransactionStatus
{
    public TransactionStatus()
    {
    }

    public TransactionStatus(Guid id, string accountId, StatusEnum statusEnum, decimal amount, bool isSuccess, string? errorMessage, TransactionTypeEnum type, DateTime createdAt)
    {
        Id = id;
        AccountId = accountId;
        StatusEnum = statusEnum;
        Amount = amount;
        IsSuccess = isSuccess;
        ErrorMessage = errorMessage;
        Type = type;
        CreatedAt = createdAt;
    }

    public Guid Id { get; set; }
    public string AccountId { get; set; }
    public StatusEnum StatusEnum { get; set;}
    public decimal Amount { get; set; }
    public bool IsSuccess { get; set; }
    public string? ErrorMessage { get; set; }
    public TransactionTypeEnum Type { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}

Then, create a new folder called “Data” and inside it add the class below:

using BankStream.Events;
using BankStream.Models;
using Microsoft.EntityFrameworkCore;

namespace BankStream.Data;

public class EventDbContext : DbContext
{
    public DbSet<DepositEvent> Deposits { get; set; }
    public DbSet<WithdrawalEvent> Withdrawals { get; set; }
    public DbSet<TransactionStatus> TransactionStatus { get; set; }

    public EventDbContext(DbContextOptions<EventDbContext> options)
        : base(options) { }
}

Now, let’s create the consumer classes. Create a new folder called “Consumers” and add to it the following classes:

• DepositConsumer

using BankStream.Data;
using BankStream.Events;
using BankStream.Models;
using MassTransit;

namespace BankStream.Consumers;

public class DepositConsumer : IConsumer<DepositEvent>
{
    private readonly EventDbContext _dbContext;

    public DepositConsumer(EventDbContext dbContext) => _dbContext = dbContext;

    public async Task Consume(ConsumeContext<DepositEvent> context)
    {
        var deposit = context.Message;

        try
        {
            await _dbContext.TransactionStatus.AddAsync(new TransactionStatus(
                Guid.NewGuid(),
                deposit.AccountId,
                StatusEnum.Completed,
                deposit.Amount,
                true,
                string.Empty,
                TransactionTypeEnum.Deposit,
                DateTime.Now)
            );

            await _dbContext.Deposits.AddAsync(deposit);

            await _dbContext.SaveChangesAsync();
        }
        catch (Exception ex)
        {
            await _dbContext.TransactionStatus.AddAsync(new TransactionStatus(
                Guid.NewGuid(),
                deposit.AccountId,
                StatusEnum.Failed,
                deposit.Amount,
                true,
                ex.Message,
                TransactionTypeEnum.Deposit,
                DateTime.Now)
            );
            await _dbContext.SaveChangesAsync();
            throw;
        }
    }
}

• WithdrawalConsumer

using BankStream.Data;
using BankStream.Events;
using BankStream.Models;
using MassTransit;

namespace BankStream.Consumers;

public class WithdrawalConsumer : IConsumer<WithdrawalEvent>
{
    private readonly EventDbContext _dbContext;

    public WithdrawalConsumer(EventDbContext dbContext) => _dbContext = dbContext;

    public async Task Consume(ConsumeContext<WithdrawalEvent> context)
    {
        var withdrawal = context.Message;
        try
        {
            await _dbContext.TransactionStatus.AddAsync(new TransactionStatus(
                Guid.NewGuid(),
                withdrawal.AccountId,
                StatusEnum.Completed,
                withdrawal.Amount,
                true,
                string.Empty,
                TransactionTypeEnum.Withdrawal,
                DateTime.Now)
            );

            await _dbContext.Withdrawals.AddAsync(context.Message);
            await _dbContext.SaveChangesAsync();
        }
        catch (Exception ex)
        {
            await _dbContext.TransactionStatus.AddAsync(new TransactionStatus(
                Guid.NewGuid(),
                withdrawal.AccountId,
                StatusEnum.Failed,
                withdrawal.Amount,
                false,
                ex.Message,
                TransactionTypeEnum.Withdrawal,
                DateTime.Now)
            );
            await _dbContext.SaveChangesAsync();
            throw;
        }
    }
}

Now, let’s analyze what is being done in both consumers.

The above classes DepositConsumer and WithdrawalConsumer use MassTransit to process events through the IConsumer<T> interface.

When a transaction event arrives, the Consume() method extracts the data from the received message and persists it to the database. In both classes, a new transaction status record (TransactionStatus) is created, making it possible to track the actions that occurred during processing.

After the transaction status is created, the deposit and withdrawal events are added to their database datasets (_dbContext.Deposits and _dbContext.Withdrawals). Finally, the changes are persisted in the database through the SaveChangesAsync() call.

Creating the Controller Class

In the controller class, we will add the endpoints for deposit and withdrawal that will call the events. So, create a new folder called “Controllers” and, inside it, add the following controller class:

• AccountController

using BankStream.Data;
using BankStream.Events;
using BankStream.Models;
using MassTransit;
using Microsoft.AspNetCore.Mvc;

namespace BankStream.Controllers;

[ApiController]
[Route("api/accounts")]
public class AccountController : ControllerBase
{
    private readonly IBus _bus;
    private readonly EventDbContext _dbContext;

    public AccountController(IBus bus, EventDbContext dbContext)
    {
        _bus = bus;
        _dbContext = dbContext;
    }

    [HttpPost("deposit")]
    public async Task<IActionResult> Deposit([FromBody] DepositEvent deposit)
    {
        await _dbContext.TransactionStatus.AddAsync(new TransactionStatus(
            Guid.NewGuid(),
            deposit.AccountId,
            StatusEnum.Pending,
            deposit.Amount,
            false,
            string.Empty,
            TransactionTypeEnum.Deposit,
            DateTime.Now)
        );
        await _dbContext.SaveChangesAsync();

        await _bus.Publish(deposit);
        return Accepted();
    }

    [HttpPost("withdrawal")]
    public async Task<IActionResult> Withdraw([FromBody] WithdrawalEvent withdrawal)
    {
        await _dbContext.TransactionStatus.AddAsync(new TransactionStatus(
             Guid.NewGuid(),
             withdrawal.AccountId,
             StatusEnum.Pending,
             withdrawal.Amount,
             false,
             string.Empty,
             TransactionTypeEnum.Withdrawal,
             DateTime.Now)
         );
        await _dbContext.SaveChangesAsync();

        await _bus.Publish(withdrawal);
        return Accepted();
    }

   [HttpGet("{accountId}/balance")]
    public IActionResult GetBalance(string accountId)
    {
        var deposits = _dbContext.
            Deposits.
            Where(d => d.AccountId == accountId)
            .Sum(d => d.Amount);

        var withdrawals = _dbContext
            .Withdrawals
            .Where(w => w.AccountId == accountId)
            .Sum(w => w.Amount);

        return Ok(deposits - withdrawals);
    }
}

Here, the controller uses the IBus interface, which is the MassTransit message bus used to publish events.

When a client makes an HTTP POST request to the /api/accounts/deposit endpoint, the Deposit() method receives a DepositEvent, representing the request for a deposit. Before publishing the event to the bus, a transaction status of Pending is recorded in the database, indicating that the operation has been requested but has not yet been completed. After persisting this status, the event is published with _bus.Publish(deposit), allowing asynchronous consumers such as DepositConsumer to process the transaction.

The same flow applies to the Withdraw method, which responds to the /api/accounts/withdrawal endpoint. It receives a WithdrawalEvent, records the transaction as Pending in the database, and publishes the event to the bus for later processing by the WithdrawalConsumer.

In addition to these two endpoints, there is a third one that is used to check the balance. To do this, instead of just fetching the value from the database as in traditional approaches, it uses the principle of Event Sourcing to reconstruct the current state through the transaction history. So, first, the totals of deposits and withdrawals are obtained, and the balance value is obtained by subtracting the total withdrawals from the total deposits.

Configuring the Program Class

In the Program class, we will configure the EventDbContext class to use the SQLite database. In addition, we will configure MassTransit and RabbitMQ to send and consume events.

So, open the Program class of your application and replace whatever is in it with the following code:

using BankStream.Consumers;
using BankStream.Data;
using MassTransit;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder
    .Services
    .AddDbContext<EventDbContext>(options => options.UseSqlite("Data Source=events.db"));
builder
    .Services
    .AddMassTransit(x =>
    {
        x.AddConsumer<DepositConsumer>();
        x.AddConsumer<WithdrawalConsumer>();
        x.UsingRabbitMq(
            (context, cfg) =>
            {
                cfg.Host("rabbitmq://localhost");
                cfg.ReceiveEndpoint(
                    "event-queue",
                    e =>
                    {
                        e.SetQueueArgument("x-message-ttl", 500000);
                        e.ConfigureConsumer<DepositConsumer>(context);
                        e.ConfigureConsumer<WithdrawalConsumer>(context);
                    }
                );
            }
        );
    });

builder.Services.AddControllers();

var app = builder.Build();

app.MapControllers();

app.Run();

Let’s analyze the code above.

After configuring SQLite, MassTransit is registered, where the two consumers are configured: DepositConsumer and WithdrawalConsumer. In addition, communication with RabbitMQ is established to transport the messages, for which the connection is established with a local host (rabbitmq://localhost).

Within the RabbitMQ configuration, a receiving endpoint called event-queue is defined. This queue is configured with the SetQueueArgument() method and a special argument, x-message-ttl, which determines the time to live of the messages within the queue. This lets us remove expired messages automatically after 500,000 milliseconds (500 seconds). This is done so that the messages can be checked in the RabbitMQ dashboard. Finally, the consumers are linked to the queue, so that any deposit or withdrawal event received by RabbitMQ will be forwarded to the appropriate consumer for processing.

Running EF Migrations

To create the database and tables, run the EF Core commands:

1. Command to install EF if you don’t have it yet:

dotnet tool install --global dotnet-ef

2. Generate the Migration files:

dotnet ef migrations add InitialCreate

3. Run the persistence:

dotnet ef database update

Setting up RabbitMQ in Docker

To run the application, you need to have RabbitMQ running locally. To do this, you can use the command below to download the RabbitMQ image and run a Docker container of it:

docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management

After running the command, you can check the RabbitQM container running on Docker Desktop:

Sending and Consuming Events

Now run the application and request the endpoint below. This post uses Progress Telerik Fiddler Everywhere to make the requests.

POST - http://localhost:PORT/api/accounts/deposit

{
  "id": "a1a7c1f2-3d4e-42b9-9e77-5f1e7c8b6c2f",
  "accountId": "123456789",
  "amount": 1300.90
}

Now, access the RabbitMQ homepage at the address indicated in Docker (you can use the default username and password guest). Then click on the “Queues and Streams” menu, then on “Get messages”, and finally “Get message(s)”.

So, you can check the data sent in the message, as well as other data such as operating system, etc., as shown in the images below:

Now let’s run the withdrawal endpoint, so make a new request to the endpoint

POST - http://localhost:PORT/api/accounts/withdraw

{
"id": "fef6df04-df3f-46a7-99a7-6d9992dd3558",
"accountId": "123456789",
"amount": 200.00
}

Then, make another request to the endpoint below to retrieve the current balance:

GET - http://localhost:PORT/api/accounts/123456789/balance

If everything goes well, you will get the result below as shown in the image.

Note that the resulting value was 1100.90. This value does not exist in the database but is the result of subtracting the deposit value of 1300.90 from the withdrawal value of 200.00.

Conclusion

Whether or not to use Event Sourcing is a choice that should be made based on the needs of the project. If you need to keep a history of changes to a specific object, such as a bank account balance, for example, Event Sourcing can be a great choice. In addition, Event Sourcing has other advantages such as easy scalability, performance, decoupling, resilience and fault tolerance.

In this post, we understand how Event Sourcing differs from traditional approaches and how to implement a bank balance management system in practice, using the resources of RabbitMQ and MassTransit for sending and consuming messages.

So, I hope this post helps you understand and implement Event Sourcing using cutting-edge resources like ASP.NET Core, RabbitMQ, MassTransit and Docker.

Now, with Karma deprecated and the Angular team without a decision about the future of unit testing in Angular, our projects continue building on top of Karma and Jasmine. It is our responsibility to find other alternatives.

In a previous article about testing in Angular, we learned about how to implement Web Test Runner in Angular. it works fine, but the Web Test Runner builder is currently EXPERIMENTAL and not ready for production use. So let’s move to another modern and stable solution—Vitest! If you play with other frameworks like Vue, React and Svelte, they use Vitest as a test runner with Vite.

Vitest … Vite? Sounds a bit confusing. Well, let’s break it down.

What Is Vite?

Vite is a modern build tool for frontend (created by Evan You, the same creator of Vue). It makes building and compiling our projects easier and faster than webpack. One great feature of Vite is that it works in phases with development and build.

When Vite works in development mode, it serves files using native ES Modules, it saves time because it doesn’t need to bundle, increasing the speed, and when it works in production, it uses Rollup to optimize, minifies, and creates bundles fast.

What Is Vitest?

Vitest was built by the Vite community; it focuses on running and providing feedback quickly for our tests and is compatible with Jest, has native support for TypeScript and uses Vite under the hood to make it faster.

When we want to use Vitest with Angular, something changes. When we use Vitest in Angular, it uses esbuild to run our tests, making it faster.

Did you know Angular uses Vite under the hood for the development server?

As always, the best way to learn to play with Vitest is by doing things, but not in the nice, perfect world of greenfield and projects from scratch with Vitest. We are going to migrate an existing project with our beloved Karma and Jasmine to Vitest.

Let’s go with our scenario!

Scenario

We want to move forward from Web Test Runner, making our app more modern using Vitest for testing. But we have some challenges in the project because we already have a few existing tests (like in other real projects) and if we’re moving to a modern way of testing, it is a good moment to also remove Jasmine? Why or why not?

So, let’s break down what we will do in the project:

• We are going to remove Jasmine, Web Test Runner and Karma (yes, the project will still have Karma in the packages, for old references with Jasmine).
• Install and configure Vitest.
• Run our tests (check if everything is green).
• Replace Jasmine test with a modern alternative (it’s a surprise).

Let’s go!

Set Up the Project

First, clone the existing project by running the following code in your terminal:

git clone https://gitlab.com/danywalls/testing-kendo-store.git
Cloning into 'testing-kendo-store'...
remote: Enumerating objects: 112, done.
remote: Counting objects: 100% (112/112), done.
remote: Compressing objects: 100% (67/67), done.
remote: Total 112 (delta 52), reused 99 (delta 39), pack-reused 0 (from 0)
Receiving objects: 100% (112/112), 294.87 KiB | 1.85 MiB/s, done.
Resolving deltas: 100% (52/52), done.

Next, create a new branch from master, with the name move-to-vitest. In this branch, we are going to make our changes to move to Vitest.

cd testing-kendo-store
git checkout -b move-to-vitest 
Switched to a new branch 'move-to-vitest'

Finally, install all dependencies and run the test to be sure everything works.

npm install
npm run test

Perfect!! The test worked, but it currently uses the Test Runner and Jasmine. We’re going to switch things up and swap those out for Vitest!

Removing Karma, Jasmine and Web Test Runner from Angular

First, in the terminal we run the following commands, to remove all Karma and Jasmine stuff and test-runner.

npm uninstall karma karma-chrome-launcher karma-coverage karma-jasmine karma-jasmine-html-reporter @types/jasmine jasmine-core

npm uninstall  @web/test-runner

OK, now it’s time to move to Vitest!

Moving to Vitest

Vitest is not natively supported by Angular, but thanks to the great work of the @analogjs team, we can bring Vitest easily into any Angular project.

npm install @analogjs/platform --save-dev  

Also, they provide great schematics to configure Vitest easily, by running the following command:

ng generate @analogjs/platform:setup-vitest

Learn more about Analog.js.

But what does platform:setup do for us?

CREATE src/test-setup.ts (327 bytes)
CREATE vite.config.mts (510 bytes)
UPDATE package.json (1070 bytes)
UPDATE tsconfig.spec.json (286 bytes)
UPDATE angular.json (2365 bytes)

It creates the test-setup.ts file to configure to testBed:

import '@analogjs/vitest-angular/setup-zone';

import {
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting,
} from '@angular/platform-browser-dynamic/testing';
import { getTestBed } from '@angular/core/testing';

getTestBed().initTestEnvironment(
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting()
);

Create the vite.config.mts to configure the jsdom, vitest plugin for Angular and Vitest configuration.

/// <reference types="vitest" />

import angular from '@analogjs/vite-plugin-angular';

import { defineConfig } from 'vite';

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {
  return {
    plugins: [
      angular(),
     
    ],
    test: {
      globals: true,
      environment: 'jsdom',
      setupFiles: ['src/test-setup.ts'],
      include: ['**/*.spec.ts'],
      reporters: ['default'],
    },
    define: {
      'import.meta.vitest': mode !== 'production',
    },
  };
});

And update the angular.json to use the analog:builder

 "test": {
          "builder": "@analogjs/vitest-angular:test"
        }
      }

OK, everything looks ready so let’s run our test!

Tada!!! Oops!! Two passes but one fail. :’( If we read the message, the failed test is app.component.spec.ts.

Let’s take a look into the app.component.spec.ts:

import {
  ComponentFixture,
  TestBed
} from "@angular/core/testing";
import {AppComponent} from "./app.component";
import { ProductsService} from "./services/products.service";
import {of} from "rxjs";
import {MOCK_PRODUCTS} from "./tests/mock";

export class MockProductService {
  public products$ = of(MOCK_PRODUCTS)
}

describe('app component', () => {
  let component: ComponentFixture<AppComponent>;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        AppComponent,
        {
          provide: ProductsService,
          useClass: MockProductService,
        },
      ],
    }).compileComponents();

    component = TestBed.createComponent<AppComponent>(AppComponent);
  });

  it('should render the product', () => {
    component.detectChanges();
    const productTitle: HTMLElement =
      component.nativeElement.querySelector('h2');
    expect(productTitle.innerText).toEqual(MOCK_PRODUCTS[0].title);
  });
});

Mmmm… this test relay in ComponentFixture , TestBed.configureTestingModule and works with lifecycle detectChanges() and query elements in the DOM. I think if we are using modern Vitest, why not move to a modern way to test in the browser? So let’s move to Angular Testing Library.

Moving to Angular Testing Library

Before we start, what is Angular Testing Library? It is a complete testing utility to help us write better and easier tests, simplify UI testing, and save time by taking care of implementation details, writing maintainable tests. It works for React, Vue, Angular, Svelte and many frameworks. If you want a post fully focused on Testing Library, leave a comment , and I promise to write about it soon.

OK, let’s get back to work. We did a great job moving from Web Test Runner to Vitest so it’s time to test the UI using Angular Testing Library.

Angular Testing Library is a wrapper of Testing Library focus in Angular.

Open your terminal to run the schematics ng add @testing-library/angular, it will install and configure the testing library in our project. During the install, it will recommend installing jest-dom and user-event; answer no.

ng add @testing-library/angular

Perfect! We are ready to move to Testing Library. It is easier than TestBed configuration because it provides two amazing functions, render and screen.

The render function helps us to configure our component to render in the DOM and provide all dependencies and screen simplifies how we query elements in the DOM, providing a huge set of methods like getById, getByText and more.

To refactor our test to the Testing Library, first remove the beforeEach method because the render will initialize the component in each test.

Finally, using the render function, we provide the AppComponent and its dependencies, similar to the configureTestingModule.

  await render(AppComponent, {
      providers: [{provide: ProductsService, useClass: MockProductService}],
    })

And finally, using screen.getByText() we query the same values as the test and expect the productTitle to exist using toBeDefined.

   const productTitle = screen.getByText(MOCK_PRODUCTS[0].title);
    expect(productTitle).toBeDefined()

The final code looks like:

import {AppComponent} from "./app.component";
import {ProductsService} from "./services/products.service";
import {of} from "rxjs";
import {MOCK_PRODUCTS} from "./tests/mock";
import {render, screen} from "@testing-library/angular";
import {expect} from "vitest";

export class MockProductService {
  public products$ = of(MOCK_PRODUCTS)
}

describe('app component', () => {

  it('should render the product', async () => {

    await render(AppComponent, {
      providers: [{provide: ProductsService, useClass: MockProductService}],
    })

    const productTitle = screen.getByText(MOCK_PRODUCTS[0].title);
    expect(productTitle).toBeDefined()
  })
});

If VS Code complains about it and describe, please open tsconfig.json, add "types": ["vitest/globals"] in the compilerOptions.

OK, save changes and run the test again!

Perfect! We have all tests in green using Vitest and Angular Testing Library!!!

For VS Code users, I recommend this extension for Vitest: https://marketplace.visualstudio.com/items?itemName=vitest.explorer.

Recap

We learned how move forward to a modern way to testing in Angular with Vitest and Testing Library. Thanks to Vitest, we can speed up our test in Angular with a very easy configuration. And combined with the power of Testing Library we can create robust UI tests without pain.

Now we don’t have any excuse not to use Vitest in our existing or new projects.

Happy testing!

Source Code:

• https://gitlab.com/danywalls/testing-kendo-store (start point)
• https://gitlab.com/danywalls/testing-kendo-store/-/tree/final-stage-19?ref_type=heads (final version).

Queues play an important role in building performant and scalable applications. They make it possible to avoid congestion in systems by streaming tasks or jobs from a producer to a consumer. Producers are just entities that add the jobs/tasks to the queue, and jobs are typically some JSON data. The worker/consumer is just a function whose job is to process the added jobs or tasks in a controlled manner without being overwhelmed.

Firebase Cloud Functions is a serverless offering by Google that allows developers to focus on writing functions without worrying about the servers they run on. When these functions are written, they can be called via HTTP like a regular web server endpoint, and they can be made to run immediately or in the background when an event happens on some resource/service. For example, when something is added to the database, or when a new file is uploaded to a storage bucket, etc.

This guide will explore one type of Cloud function called Task Queue Functions that automatically leverage Google’s Cloud Tasks API. This is an API that makes it easy for us to use queues. Our use case will be a simple ecommerce app that needs to send emails to users. After processing dummy orders, we will store email-sending requests in a queue and add workers function to send actual emails to the user’s inbox. We will explore the options that can be used to enqueue tasks to the queue.

Prerequisites

To follow along with this guide, it is assumed you understand Firebase and are familiar with JavaScript and comfortable with basic TypeScript.

Google Cloud Tasks API and Task Queue Functions

Let’s briefly describe the Cloud Tasks API and where task queue functions come in. The idea here is to see how these two are related and how they are intended to be used.

The Cloud Tasks API is based on four core constructs: queues, tasks/jobs, handlers/workers and targets.

The queue holds the task. The task is some data, typically a plain JavaScript object. The handler/worker is the function that completes the task. The target refers to the environment where the worker runs. A task is added by making an HTTP request to the Cloud Tasks API, which adds it to the queue, after which the task is then dispatched to the worker to handle it.

The essence of this API is to make it budget-friendly and easy for developers to offload resource-intensive background tasks to queues and then connect worker functions that will process or handle the tasks in the queue. The use case for this API is best suited strictly for tasks that need to be done in the background and do not require immediate results from processing that task. Make sure that your use case fits into this area before using the API.

Some examples of such tasks include:

• Sending emails
• Updating analytics
• Coordinated access to a third party that is rate-limited

While the basic explanation of this API sounds simple, there are some caveats to note. First, even though directly interacting with the Cloud Tasks API allows for more dynamism and supports many use cases, using and understanding all its moving parts can be challenging for a new developer who just wants to have everything working.

The Cloud Tasks API is structured so that when queues are created, the developer has to create the environment (target) separately and add the worker function that will process tasks that will be added to the queue. In some cases, this may also need to handle scaling of the workers under intense workloads. Task functions simplify this.

Task functions are cloud functions that make it easy for the developer to write a worker function and declaratively write the settings for the queue. Under the hood, Firebase takes care of the rest. It interacts with the Cloud Tasks API, creates the queue and connects the worker function to it. It also handles all the scaling related logic so that enough worker functions are spawned when necessary and killed with little or no effort by the developer.

What We Will Be Building

Our mini-application will be a simple ecommerce app that needs to send users emails after processing their order. For this, we will be defining two cloud functions.

First, we will start with the main task queue function, which will manage the queue containing the email-sending tasks. We will add the worker function, which will send emails using EmailJS. Then, we will test our task queue function locally by calling it via HTTP.

Next, to make our setup feel more like a real-world app, we will create another cloud function, which will be a regular user-facing HTTP endpoint that simulates a simple order processing endpoint. This function will not do anything fancy here; we will just show how to queue email-sending tasks from this function and trigger the task queue function’s worker to execute the task.

We will deploy both functions to a live URL and go over how to expose them in production via HTTP endpoints. We will test all endpoints during development or production.

Project Setup

Let’s put everything we will need in place before we begin. We will be doing three things mainly:

• Setting up a Firebase project
• Setting up cloud functions locally using the Firebase project
• Setting up EmailJS for sending emails

Create a Firebase Project

Visit the Firebase console to create a project. Give your project a name. As shown below, I’m calling mine “awesome project”.

If you plan to follow this guide and only test locally, you can omit this step. However, since we plan to deploy our cloud functions and use the Cloud Tasks API, we need to enable billing on the Firebase project we just created.

You get up to one million free calls when using the Cloud Tasks API, so feel free to add a billing account.

Initialize Cloud Functions from the Firebase Project

Now, let’s set up a cloud functions project locally. We will start by installing the required Firebase tools needed to do this.

If you have Node.js installed on your system, open your terminal and run this command:

npm install -g firebase-tools

Next, you need to authenticate by running firebase login. Then, you can create a directory of your choice on your device by running mkdir cloud-tasks && cd cloud-tasks.

Then, initialize your project by running firebase init. In the prompt, select the features you want to add to your project. Select cloud functions and emulators. Emulators allow you to test the project locally.

Next, let’s choose the Firebase project we created on the authenticated account and connect it to our local setup.

We will write our functions in TypeScript and use cloud tasks and functions. We will only choose their respective emulators since that is what we will need.

If everything is done correctly, your project setup should look like this:

Next, run the following command to install the dependencies for our Cloud Functions project.

cd functions
npm install

As of the time of writing, it is important to note that Cloud Functions are compatible when testing locally and in production for Node.js versions 18 through 20. However, Node.js 22 is only supported for previewing the project when testing locally. If you get an error about your Node version when running the command above, and you are using Node.js 22, you can update the engines property in your functions/package.json file.

// Update the engines property from this:
"engines": {
        "node": "18"
    },

//to this:
    "engines": {
        "node": "22"
    },

Set Up EmailJS for Emails

EmailJS is a service that makes it easy to send emails directly from a client or serverside app. Visit the EmailJS website and create an account. Then, on the dashboard, set up a service.

We can use the Gmail service since emails will be sent from a personal account. Feel free to select any service of your choice. Once you have created a service, it will be displayed in the services list. Take note of the Service ID.

Next, we need to create an email template. In the Email Templates section, click Create New Template.

Our template will take four parameters that are quite intuitive.

Here are some of them:

• title: The title of the email
• body: The raw HTML representing the body of the email. Notice it’s wrapped in 3 braces, i.e., {{{body}}}
• recipient: The email address of the receiver

Once you are done, save the template. You should see the newly created template, as shown below. Make sure you take note of the template ID.

Finally, we need to get our API keys. You can retrieve them in the Account section.

In the functions folder of the project, create a .env file and add the following to it:

GMAIL_SERVICE_ID = ENTER - EMAILJS - SERVICE - ID;
EMAIL_SERVICE_PRIVATE_KEY = ENTER - EMAILJS - PRIVATE - KEY;
EMAIL_SERVICE_PUBLIC_KEY = ENTER - EMAILJS - PUBLIC - KEY;

Since we will be making HTTP requests to the EmailJS server, we will also need Axios. From the functions directory, run the following command in your terminal:

npm i axios

Add Task Queue Function for Sending Emails

Add the following to your functions/src/index.ts file:

import { onTaskDispatched, Request } from "firebase-functions/tasks";
import axios from "axios";
import { initializeApp } from "firebase-admin/app";
initializeApp();

type notificationTask = {
  recipients: string[];
  title: string;
  body: string;
};
exports.handleNotification = onTaskDispatched(
  {
    retryConfig: {
      maxAttempts: 2,
      minBackoffSeconds: 30,
    },
    rateLimits: {
      maxConcurrentDispatches: 5,
    },
  },
  async (req: Request<notificationTask>) => {
    const data = req.data;
    await sendEmail("template_tz98ape", {
      title: data.title,
      body: data.body,
      recipient: data.recipients[0],
    });
    return;
  }
);
async function sendEmail(templateId: string, params: any) {
  await axios.post("https://api.emailjs.com/api/v1.0/email/send", {
    service_id: process.env.GMAIL_SERVICE_ID,
    template_id: templateId,
    template_params: params,
    accessToken: process.env.EMAIL_SERVICE_PRIVATE_KEY,
    user_id: process.env.EMAIL_SERVICE_PUBLIC_KEY,
  });
  return true;
}

In the code above, we use initializeApp to set up the Cloud Functions project using the Firebase project we linked to it earlier. This function has to be called first before any other code. Every project has a default service account that allows the app to access one or more resources, and this call verifies that our application is ready to interface with the cloud.

Next, we called our task queue function handleNotification. Task queue functions are created using the onDispatch function, which expects two parameters: the first is an object that allows us to declaratively specify how we want to configure the queue and its behavior, and the second is the actual worker function.

For the queue options, we use its retryConfig property and specify that each task in the queue should be retried a maximum of two times if it fails. We also specified that each time it fails, there should be a delay of 30 seconds before trying it again.

We also specified that if many tasks are in the queue, at least five should be processed at once. This means that, at most, five instances of the worker function should be spawned in those situations.

The worker function is the second parameter passed to the onDispatch function. Worker functions only accept a request object. Since they are not meant to return a response, each time a worker function is called, the task payload is contained in the request’s body. In our case, our notification task payload type looks like this:

type notificationTask = {
  recipients: string[];
  title: string;
  body: string;
};

It is retrieved from the request body and then used to invoke the sendEmail function to send the email.

You can create and configure powerful customized queues with task queue functions with just a few lines of code and get things to work.

To test our function, run npm run serve, then head over to localhost:4000. In the logs tab, you should see that our handleNotification task queue function is initialized and ready to be called.

Now, let’s add a task to our queue and then trigger the worker function in Progress Telerik Fiddler Everywhere.

To avoid errors, when adding a task, the request body must contain a data property that holds the contents of the task. In our case, we added our notification task payload. When we make the request, we add the task to the queue via the Cloud Tasks API, and we get back the 204 response.

Later, the Cloud Tasks API will dispatch the task to the worker function to run it. This makes the response time short since the call has no business with the worker directly.

Upon successful execution of the worker, when we check the user’s inbox we should see the email as shown below.

Enqueueing Tasks from Another Cloud Function

We have been able to explore task queue functions, but we are still missing one thing—adding practicality to their usage. In this section, we will be looking at the following:

• In a real-world app like our dummy ecommerce app, email sending typically happens after an order has been processed, so it is common for us to queue notification tasks from a separate function.
• For security reasons and because we know the task producers, we may not want to expose an endpoint that can be called directly to add tasks to the task queue, as we did in Fiddler.

In view of all this, we will define another simple Cloud Function to process orders. It will simply interact with the Cloud Tasks API and enqueue a notification task. Let’s now update our functions/scr/index.ts file with the following:

import { onRequest } from "firebase-functions/v2/https";
import { onTaskDispatched, Request } from "firebase-functions/tasks";
import axios from "axios";
import { getFunctions } from "firebase-admin/functions";
import { initializeApp } from "firebase-admin/app";
initializeApp();
// Start writing functions
// https://firebase.google.com/docs/functions/typescript
type notificationTask = {
  recipients: string[];
  title: string;
  body: string;
};

exports.handleNotification = onTaskDispatched(
  {
    //... queue options
  },
  async (req: Request<notificationTask>) => {
    //....
  }
);
async function sendEmail(templateId: string, params: any) {
  //....
}
type order = {
  order_id: string;
  order_date: string;
  customer: {
    customer_id: string;
    name: string;
    email: string;
  };
  items: {
    item_id: string;
    name: string;
    quantity: number;
    price_per_unit: number;
    subtotal: number;
  }[];
  payment: {
    payment_id: string;
    method: string;
    status: string;
    amount: number;
    currency: string;
    transaction_id: string;
  };
  order_status: string;
  notes: string;
};
export const processOrder = onRequest(async (request, response) => {
  const order: order = request.body;
  const queue = getFunctions().taskQueue("handleNotification");
  const notification: notificationTask = {
    recipients: [order.customer.email],
    title: "order processed succussfully",
    body: `<h2>dear ${order.customer.name} , your order has been processed successfully</h2>`,
  };
  queue.enqueue(notification, {
    scheduleDelaySeconds: 5,
  });
  response.json({
    message: "order processed successfully!",
  });
});

We defined an HTTP function called processOrder using the onRequest function from the firebase-functions library. Our HTTP function simulates a dummy endpoint that expects an order as a payload. Using getFunctions().taskQueue("handleNotification"), the reference to the handleNotification queue is retrieved. It constructs a notification task and then enqueues it to the task queue using its enqueue method.

When using enqueue, we pass two arguments: the task and a configuration on the task. In our case, we just set a delay of 5 seconds. There are many things that can be configured here; for example, you can specify the exact time you want the task to run, etc.

Let’s now proceed to test the function locally again. In your terminal, run npm run serve, head over to Fiddler, and call the function using the URL printed in the logs section of your emulator suite.