DEV Community: Tim Deschryver

Announcing NgRx 21: Celebrating a 10 Year Journey with a fresh new look and @ngrx/signals/events

Tim Deschryver — Mon, 22 Dec 2025 08:59:27 +0000

We are pleased to announce the latest major version of the NgRx framework with some exciting new features, bug fixes, and other updates.

10 Year Anniversary 🎉

Ten years ago, NgRx started as a small experiment created by Rob Wormald, Mike Ryan, and Brandon Roberts to bring Redux-style state management to Angular applications. Since then, Angular has changed a lot, our tooling has changed a lot, and the way we build applications has changed a lot – but NgRx is still the go-to solution many of us reach for managing state in Angular.

Over the years, NgRx has grown from @ngrx/store into a full platform: router integration, entity helpers, devtools, component utilities, ESLint rules, and most recently Signals.

Huge thanks to Alex Okrushko, Brandon Roberts, Marko Stanimirović, Mike Ryan, Rainer Hahnekamp, Tim Deschryver, everyone who has been on the team along the way, and the many contributors. Equally important are the countless content creators who helped the rest of us learn how to use these tools well.

If you have used NgRx in the last decade, you’re part of that story. Thank you. 🙏

Some key-numbers to highlight teams are confident that NgRx brings value when building quality production-ready applications throughout these years:

483 contributors
2.250 commits
2.400 issues closed
@ngrx/store has been downloaded 174.070.253 times
@ngrx/signals has been downloaded 14.665.960 times

New Website 🎨

To celebrate this milestone we’re shipping a refreshed website at https://ngrx.io.

The new site is build with Analog and has a modernized look and feel, improved navigation, and better performance. We're also looking to update the docs and examples to make it easier to find what you need, whether you're just getting started or looking for advanced patterns.

A huge shout-out to Mike Ryan for the new design and setup for the new website, and to Brandon Roberts, Duško Perić, and Tim Deschryver for the content migration and improvements.

Welcome Rainer 🏆

We are thrilled to welcome Rainer to the NgRx core team! Rainer has been an active member of the NgRx community for years, from giving talks and workshops at conferences and meet-ups, to contributing code, documentation, and support to fellow developers. His expertise and passion for Angular and NgRx make him a valuable addition to our team. Please join us in welcoming Rainer to the NgRx family!

The Events Plugin is stable 👏

In NgRx 19 we introduced @ngrx/signals/events as an experimental way to model event-driven workflows in your Angular applications using Signals and Signal Stores.

Thanks to your feedback the APIs have been cleaned up and the rough edges have been sanded down. This makes us confident to promote the Events plugin to stable in this release.

If you want to explore how to use Events plugin in your app, check out the Events documentation.

The addition of Scoped Events

The most important addition is support for scoped events. Instead of broadcasting every event globally, you can scope events to a specific part of your app – the local scope, parent scope, or the global scope. Typical examples include local state management scenarios where events should stay within a specific feature, or micro-frontend architectures where each remote module needs its own isolated event scope.

import { provideDispatcher } from '@ngrx/signals/events';

@Component({
  providers: [
    // 👇 Provide local `Dispatcher` and `Events` services
    // at the `BookSearch` injector level.
    provideDispatcher(),
    BookSearchStore,
  ],
})
export class BookSearch {
  readonly store = inject(BookSearchStore);
  readonly dispatch = injectDispatch(bookSearchEvents);

  constructor() {
    // 👇 Dispatch event to the local scope.
    this.dispatch.opened();
  }

  changeQuery(query: string): void {
    // 👇 Dispatch event to the parent scope.
    this.dispatch({ scope: 'parent' }).queryChanged(query);
  }

  triggerRefresh(): void {
    // 👇 Dispatch event to the global scope.
    this.dispatch({ scope: 'global' }).refreshTriggered();
  }
}

To learn more about scoped events, check out the scoped events documentation.

`signalMethod` and `rxMethod` accept a computation method

In addition to providing a Signal, it is also possible to provide a computation function to the methods signalMethod and rxMethod. This is a small change that improves the developer experience, and aligns our API with Angular's resource and linkedSignal methods.

@Component({
  /* ... */
})
export class Numbers {
  readonly logSum = signalMethod<{ a: number; b: number }>(
    ({ a, b }) => console.log(a + b)
  );

  constructor() {
    const num1 = signal(1);
    const num2 = signal(2);
    this.logSum(() => ({ a: num1(), b: num2() }));
    // console output: 3

    setTimeout(() => num1.set(3), 3_000);
    // console output after 3 seconds: 5
  }
}

Special thanks to Rainer and Marko for their incredible work on @ngrx/signals!

Updating to NgRx v21 🚀

To start using NgRx 21, make sure to have the following minimum versions installed:

Angular version 21.x
Angular CLI version 21.x
TypeScript version 5.9.x
RxJS version ^6.5.x or ^7.5.x

NgRx supports using the Angular CLI ng update command to update your NgRx packages. To update your packages to the latest version, run the command:

ng update @ngrx/store@21
ng update @ngrx/signals@21

A Big Thank You to Our Community! ❤️

NgRx is a community-driven project, and we are immensely grateful for everyone who contributes their time and expertise. Your bug reports, feature requests, documentation improvements, and pull requests are what make this project thrive.

We want to give a special shout-out to a few individuals for their direct contributions to this release:

Duško Perić for improving the website's design
Exequiel Ceasar Navarrete, Gabriel Guerrero, Julien Michel, and Mateusz Stefańczyk for migrating the test suite to Vitest.
J. Degand for quality of life improvements.

We also want to extend a huge thank you to our sponsors. Your financial support is crucial for the continued development and maintenance of NgRx.
A special thanks to our Gold sponsor, Nx, and our Bronze sponsor, House of Angular.

Sponsor NgRx 🤝

If you are interested in sponsoring the continued development of NgRx, please visit our GitHub Sponsors page for different sponsorship options, or contact us directly to discuss other sponsorship opportunities.

What's Next?

We are incredibly excited about what you will build with NgRx v21. We encourage you to try out the new features and share your feedback with us. We are especially interested in hearing your thoughts on the new experimental Events plugin. Please open issues and discussions on our GitHub repository to let us know what you think.

To stay up-to-date with the latest news, follow on X / Twitter and LinkedIn.

Thank you for being part of the NgRx community! Happy coding!

Announcing NgRx 18: NgRx Signals is almost stable, ESLint v9 Support, New Logo and Redesign, Workshops, and more!

Tim Deschryver — Thu, 13 Jun 2024 19:41:00 +0000

We are pleased to announce the latest major version of the NgRx framework with some exciting new features, bug fixes, and other updates.

Stable NgRx Signals 🚦 (it's almost there)

Update (2024-07-25): NgRx Signals is officially released, take a look at the Release Post for more info.

In NgRx version 17 we announced NgRx Signals, which was and still is in developer preview.
From the first release Marko Stanimirović further improved and stabilized @ngrx/signals with the help of the community. A special thanks to Rainer Hahnekamp for his thoughts, feedback, and the provided help.

There are still some loose ends that need to be ironed out, but we're planning to officially release a stable version in one of the next minor releases. We're confident that this brings a solid, flexible, and scalable reactive state management solution with good developer ergonomics for Angular Signals.

This means that after a year of hard work, we're getting close to getting @ngrx/signals out of the the developer preview phase.

From the look of it our users are ready for the release, as we're seeing a lot of excitement and positive feedback. The numbers also show that the usage of @ngrx/signals is increasing gradually, hitting 50k downloads per week.

To get started with @ngrx/signals, install the package via one of the commands below and follow the @ngrx/signals Guide.

npm install @ngrx/signals

You can also use the ng add command:

ng add @ngrx/signals

ESLint Plugin support for ESLint v9 🧹

In this release, we've added support for ESLint v9. This means that you can now use the NgRx ESLint plugin with the latest version of ESLint. The plugin is designed to help you write better NgRx code by providing rules that enforce best practices and help you avoid common mistakes for working with packages from the NgRx platform.

We also took the opportunity to update the pre-configured rules to make it easier for you to get started with the plugin, including new new set of rules for @ngrx/signals.
If you're experiencing any issues with the plugin, please check the updated documentation to find the new subdivisions of our rules.

You don't have to worry about the compatibility of the plugin, because we've ensured that this is backwards compatible with older versions of ESLint as well.
If you're interested in using the plugin with ESLint v9, you can import and configure the plugin from @ngrx/eslint-plugin/v9:

const tseslint = require("typescript-eslint");
const ngrx = require("@ngrx/eslint-plugin/v9");

module.exports = tseslint.config({
  files: ["**/*.ts"],
  extends: [
    // 👇 Use all rules or only import the rules for a specific package
    ...ngrx.configs.all,
    ...ngrx.configs.store,
    ...ngrx.configs.effects,
    ...ngrx.configs.componentStore,
    ...ngrx.configs.operators,
    // 🎉 New rules for @ngrx/signals
    ...ngrx.configs.signals,
  ],
  rules: {
    // 👇 Configure specific rules
    "@ngrx/with-state-no-arrays-at-root-level": "warn",
  },
});

If you want to migrate to ESLint v9, we encourage to update Angular ESLint to the latest version (v18) as well.

New NgRx Operators Package 🛠️

In NgRx v17 we introduced the new package @ngrx/operators as a place for common and useful RxJS operators that are used in Angular applications.

The v18 release continues the migration of the concatLatestFrom (from @ngrx/effects) and tapResponse (from @ngrx/component-store) RxJS operators to @ngrx/operators. From NgRx v18 the operators are only available from @ngrx/operators and are no longer part of the @ngrx/effects and @ngrx/component-store packages.

New Logo and Redesign of ngrx.io 💅

If you haven't noticed yet, we've updated the NgRx logo to a new look that follows the new Angular branding.
Many thanks to designs from our community, in the end we decided to go with the design from Robin Goetz, thanks Robin!.
The new logo (in purple and white) can be found on our Press Kit page, so make sure you've updated the logo in your content.

After using our website ngrx.io for a while now, we're thinking that it's time for a redesign.
Behind the scenes Mike Ryan is working on a new version of the NgRx website.

The new website is build up from scratch using Analog.js and will have a brand-new design and revamped content.
This to make sure to offer the best possible experience to our users and to make it easier to find the information you need.
It also ensures that the website will become easier to maintain and update.

Because we're a community-driven project, we're keeping in mind that the website should be easy to contribute to.

Deprecations and Breaking Changes 💥

This release contains bug fixes, deprecations, and breaking changes. For most of these deprecations or breaking changes, we've provided a migration that automatically runs when you upgrade your application to the latest version.

We want to highlight one breaking change in particular, which we expect to have a big impact.
Because we've seen many users import the TypedAction type via a deep import (which is not recommended), we've decided to merge the TypedAction type with the Action type in the @ngrx/store package. If you're using the ng update schematics, the migration automatically updates your imports to use the new location.

Take a look at the version 18 migration guide for complete information regarding migrating to the latest release. The complete CHANGELOG can be found in our GitHub repository.

Upgrading to NgRx 18 🗓️

To start using NgRx 18, make sure to have the following minimum versions installed:

Angular version 18.x
Angular CLI version 18.x
TypeScript version 5.4.x
RxJS version ^6.5.x or ^7.5.x

NgRx supports using the Angular CLI ng update command to update your NgRx packages. To update your packages to the latest version, run the command:

ng update @ngrx/store@l8

If your project uses @ngrx/component-store or @ngrx/signals, but not @ngrx/store, run the following command:

ng update @ngrx/component-store@18
ng update @ngrx/signals@18

NgRx Workshops 🎓

With NgRx usage continuing to grow with Angular, many developers and teams still need guidance on how to architect and build enterprise-grade Angular applications. We are excited to introduce upcoming workshops provided directly by the NgRx team!

We're offering one to three full-day workshops that cover the basics of NgRx to the most advanced topics. Whether your teams are just starting with NgRx or have been using it for a while - they are guaranteed to learn new concepts during these workshops.

The workshop covers both global state with NgRx Store and libraries, along with managing local state with NgRx ComponentStore and NgRx Signals.

Visit our workshops page to sign up from our list of upcoming workshops. The next workshops are scheduled for September 18-20 (US-based time) and October 16-18 (Europe-based time).

Swag Store and Discord Server 🦺

You can get official NgRx swag through our store! T-shirts with the NgRx logo are available in many different sizes, materials, and colors. We will look at adding new items to the store such as stickers, magnets, and more in the future. Visit our store to get your NgRx swag today!

Join our Discord server for those who want to engage with other members of the NgRx community, old and new.

Contributing to NgRx 🥰

We're always trying to improve the docs and keep them up-to-date for users of the NgRx framework. To help us, you can start contributing to NgRx. If you're unsure where to start, come take a look at our contribution guide and watch the introduction video Jan-Niklas Wortmann and Brandon Roberts have made to help you get started

Thanks to all our contributors and sponsors! 🏆

NgRx continues to be a community-driven project. Design, development, documentation, and testing all are done with the help of the community. Visit our community contributors section to see every person who has contributed to the framework.

If you are interested in contributing, visit our GitHub page and look through our open issues, some marked specifically for new contributors. We also have active GitHub discussions for new features and enhancements.

We want to give a big thanks to our Gold sponsor, Nx! Nx has been a longtime promoter of NgRx as a tool for building Angular applications, and is committed to supporting open source projects that they rely on.

We want to thank our Bronze sponsor, House of Angular!

Lastly, we also want to thank our individual sponsors who have donated once or monthly.

If you are interested in sponsoring NgRx, visit our GitHub sponsors page.

Assertion Scopes, the one FluentAssertions feature you didn't know you needed

Tim Deschryver — Fri, 18 Nov 2022 15:22:13 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Read the TLDR version on timdeschryver.dev

Hi, let me quickly tell you about a useful feature of FluentAssertions that many of us don't know exists.
The feature is called Assertion Scopes, and it helps you to faster understand why a test fails.

If you have never heard of FluentAssertions, it's a library that, as the name entails, lets you write test assertions with a fluent API instead of using the methods that are available on Assert.
The library is test runner agnostic, meaning that it can be used with MSTest, XUnit, NUnit, and others.
I find that FluentAssertions improves the readability of the test assertions, and thus I can encourage you to take a look at it if you haven't already.

Now, let's get back to the point of this blog post, Assertion Scopes.

I've seen many tests that often don't test a single outcome.
Instead, a test case consists of multiple multiple assertions.
These assertions usually follow each other to test the expected outcome in its entirety.

To give a simple example, let's take a look at the following tests.
The test creates a new person and verifies if the first name and the last name have the correct value.

using FluentAssertions;

namespace DemoTests;

public class Tests
{
    [Test]
    public void Test1()
    {
        var person = new Person { FirstName = "Elaine" , LastName = "Benes"};

        person.FirstName.Should().Be("elaine");
        person.LastName.Should().Be("benes");
    }

    class Person
    {
        public required string FirstName { get; init; }
        public required string LastName { get; init; }
    }
}

Of course, this test fails because the expected names are not correct.
Resulting in the next error message.

Error Message:
    Expected person.FirstName to be "elaine", but "Elaine" differs near "Elaine" (index 0).
Stack Trace:
    ...

As we can see, the output only shows the first error message.
In a real scenario, the next step is to fix the first assertion and then to run the test again.

This results that the test is failing for a second time, but instead of the first error message, we now get the second message.

Error Message:
    Expected person.Name to be "benes", but "Benes" differs near "Bennes" (index 0).
Stack Trace:
    ...

If you ask me, this isn't very productive.

We have to rerun the failing test(s) multiple times to get the full picture.
To get to a green test, we have to work our way through the invalid messages.

This isn't a problem for this simple test case.
But when tests are taken a little bit longer to run, e.g. integration tests (and I'm a big fan of integration tests), it can become unpleasant to work with.

Luckily there's a solution for this.

When I asked others' opinions on how they read the above snippet, most of the answers I received were among the lines that the test verifies if the first name is correct and if the last name is correct.
This mindset is where I think the problem lies.
Instead of thinking in single independent assertions (tests) cases within a test case, the better way to look at it would be to say "The test case verifies if the person is created correctly".

We could rewrite the assertion to use another method from FluentAssertions (for example BeEquivalentTo).
But, while it does seem good for this simple test case, it might not be that readable for more complex class structures.
Also, other examples might not have an API to assert multiple conditions that belong together, e.g. to verify if all side effects are triggered.

That's where an Assertion Scope is beneficial.
With it, it's possible to create a group of assertions that are tested together.

All assertions within that group are executed regardless of their outcome.
If one (or more) assertion(s) fail, the rest of the assertions are still executed.
Afterward, we get a nice compact overview containing the assertion(s) that have failed.

The refactored test case that uses an Assertion Scope looks like this:

using FluentAssertions;
using FluentAssertions.Execution;

namespace DemoTests;

public class Tests
{
    [Test]
    public void Test1()
    {
        var person = new Person { FirstName = "Elaine" , LastName = "Benes"};

        using (new AssertionScope())
        {
            person.FirstName.Should().Be("elaine");
            person.LastName.Should().Be("benes");
        }
    }

    class Person
    {
        public required string FirstName { get; init; }
        public required string LastName { get; init; }
    }
}

Resulting in the following output.
As before, we get the same messages.
The big difference is that we now get them all at once instead of one by one.

Error Message:
    Expected person.FirstName to be "elaine", but "Elaine" differs near "Elaine" (index 0).
    Expected person.Name to be "benes", but "Benes" differs near "Bennes" (index 0).
Stack Trace:
    ...

I also encourage you to give a description to the scope by passing in a description as an argument.
This makes it very explicit that assertions belong to each other, and also gives a clear view of why the test fails.

using FluentAssertions;
using FluentAssertions.Execution;

namespace DemoTests;

public class Tests
{
    [Test]
    public void Test1()
    {
        var person = new Person { FirstName = "Elaine" , LastName = "Benes"};

        using (new AssertionScope("The person is created with the correct names"))
        {
            person.FirstName.Should().Be("elaine");
            person.LastName.Should().Be("benes");
        }
    }

    class Person
    {
        public required string FirstName { get; init; }
        public required string LastName { get; init; }
    }
}

To see the differences, you can compare the next error messages with the previous ones.

Error Message:
    Expected The person is created with the correct names to be "elaine",
    but "Elaine" differs near "Elaine" (index 0).

    Expected The person is created with the correct names to be "benes",
    but "Benes" differs near "Bennes" (index 0).
Stack Trace:
    ...

Conclusion

With Assertion Scopes provided by the FluentAssertions library, we can group multiple assertions into a single "transaction".
This has the benefit that when a test fails, you are immediately presented with the bigger picture.
In contrast to not using them, where you have to re-execute the same test over and over again until all assertions are fixed.
Not only does this increase the developer experience, it also increases the productivity of you and your team.

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

You should take advantage of the improved NgRx APIs

Tim Deschryver — Fri, 11 Nov 2022 09:18:05 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Over the past years, TypeScript has become more powerful. Especially when it comes to its type system, in other words, how smart Typescript is.
With every new release, there's always one or more features that make it easier to write better code.

This is something that NgRx leverages to its full potential.
NgRx uses new TypeScript features to build type-safe state management libraries, which makes NgRx easier to use and shortens the feedback loop to detect problems earlier.

Sadly, keeping up with everything is time-consuming, and a lot of examples are outdated.
I hope that this post helps you to get to discover (and use) the latest APIs that NgRx has to offer.

Most of these tips and tricks are available as rules in the NgRx ESLint Plugin.
Some updated APIs also have an automatic migration that is run via the ng-update command, other might have an ESLint fixer to refactor the code to the (newer) recommended syntax.

Let's start off at the base of NgRx, Actions.

Actions

You can take a look at the documentation to learn more about Actions.

We can summarize this section into one sentence, stop defining actions as classes.

import { Action } from "@ngrx/store";

export enum CustomerPageActionTypes {
    CustomersLoaded = '[Customers Page] Customers Loaded',
    CustomerDetailLoaded = '[Customers Page] Customer Detail Opened'
}

// Action without payload
export class CustomersLoaded implements Action {
    readonly type = CustomerPageActionTypes.CustomersLoaded;
}

// Action with payload
export class CustomerDetailLoaded implements Action {
    readonly type = CustomerPageActionTypes.CustomerDetailLoaded;
    constructor(public payload: { customerId: string }) {}
}

export type CustomerPageActions = CustomersLoaded | CustomerDetailLoaded;

While it's still supported, NgRx has a more robust way to define actions.

Previously, the above snippet was the way to define actions in NgRx because it was the only way to keep reducers type-safe (more on this in reducers).

In the newer version(s) of NgRx (v8+), we can now use the createAction method to define actions.
This way is less error-prone, and is also automatically type-safe.

The equivalent of the above snippet can be refactored to the following actions.

import { createAction, props } from "@ngrx/store";

// Action without props (payload)
export const customersLoaded = createAction("[Customers Page] Customers Loaded");

// Action with props (payload)
export const customerDetailLoaded = createAction(
    "[Customers Page] Customer Detail Opened",
    props<{ customerId: string }>()
);

Also, it's important to notice that we aren't required to define the CustomerPageActions union type anymore.

Since NgRx v14, it's possible to group actions that share the same source with createActionGroup.
The only caveat is that you can't use your IDE refactoring tools to rename the action or to find all its occurrences, but on the other hand, this shouldn't be a problem.

We can detect where an action is dispatched by looking at its source, and renaming an action (event) should be a rare occasion - I would prefer to create a new action in this case because it mostly means that it's another unique event.

import { createActionGroup, emptyProps, props } from "@ngrx/store";

export const CustomerPageActions = createActionGroup({
    source: "Customers Page",
    events: {
      // Action without props
      'Customers Loaded': emptyProps(),
      // Action with props
      'Customer Detail Opened': props<{ customerId: string }>(),
    },
});

// Generates the following actions that can be dispatched
CustomerPageActions.customerDetailOpened({ customerId: 'CUST-123' });
CustomerPageActions.customersLoaded()

Reducers

You can take a look at the documentation to learn more about Reducers.

We've seen how to create actions, let's take a look at how these are consumed in reducers.

The reducer is a "simple" function that receives the current state, and the dispatched action.
Within the reducer, there's a switch statement to handle the proper state updates.

To make the reducer type safe the dispatched action needs to be annotated with the action union type.
When a reducer handles actions from different sources, all union types need to imported.

Within a case block, action has the correct type.

It's very important to add a default case to return the state as-is for the actions that aren't consumed by the reducer.
If you don't do this, the state is cleared (state will be undefined).

import { CustomerPageActions, CustomerPageActionTypes } from "./customer-page.actions";

const initialState = {
    customers: [],
    selectedCustomerId: null
};

export function customersReducer(state = initialState, action: CustomerPageActions) {
  switch (action.type) {
    case CustomerPageActionTypes.CustomersLoaded:
        return { ...state, customers: [] };
    case CustomerPageActionTypes.CustomerDetailLoaded:
        return { ...state, selectedCustomerId: action.payload.customerId };
    default:
      return state;
  }
}

In other words, to make the reducer type-safe we have to manually create additional types.

From NgRx v8, this isn't the case anymore.
There's a better way to define reducers compared to the reducer method, which is createReducer.

Instead of the reducer method with switch cases, we now have:

createReducer to replace the reducer method
the on method to listen for one or multiple action(s), replacing a switch case

Again, the main benefit of this approach is that it's more robust and type-safe by default (without additional steps).

The refactored version using createReducer looks like this.

import { createReducer, on } from "@ngrx/store";
import { customersLoaded, customerDetailLoaded } from "./customer-page.actions";

const initialState = {
    customers: [],
    selectedCustomerId: null
};

export const customersReducer = createReducer(
  initialState,
  on(customersLoaded, (state) => ({ ...state, customers: [] })),
  on(customerDetailLoaded, (state, action) => ({ ...state, selectedCustomerId: action.customerId  }))
);

The same reducer, but with actions created with createActionGroup uses the CustomerPageActions group instead of the loose actions.

import { createReducer, on } from "@ngrx/store";
import { CustomerPageActions } from "./customer-page.actions";

const initialState = {
    customers: [],
    selectedCustomerId: null
};

export const customersReducer = createReducer(
    initialState,
    on(CustomerPageActions.CustomersLoaded, (state) => ({ ...state, customers: [] })),
    on(CustomerPageActions.CustomerDetailLoaded, (state, action) => ({ ...state, selectedCustomerId: action.customerId  }))
);

The only downside is that createReducer doesn't support a default case.

To take it a step further, we can use the createFeature method, which is introduced in NgRx v12.1.
With it, the reducer is wrapped in a feature (more on this in Registering the Store).
But more important, a default set of selectors are generated based on the state properties.

import { createReducer, on, createFeature } from "@ngrx/store";
import { CustomerPageActions } from "./customer-page.actions";

const initialState = {
    customers: [],
    selectedCustomerId: null
};

const customersFeature = createFeature({
  name: "customers",
  reducer: createReducer(
      initialState,
      on(CustomerPageActions.CustomersLoaded, (state) => ({ ...state, customers: [] })),
      on(CustomerPageActions.CustomerDetailLoaded, (state, action) => ({ ...state, selectedCustomerId: action.customerId  }))
  ),
});

// Automatically generates the following selectors:
customersFeature.selectCustomersState
customersFeature.selectCustomers
customersFeature.selectSelectedCustomerId

Selectors

You can take a look at the documentation to learn more about Selectors.

Selectors remained the same throughout the NgRx versions, so there's not much to say about them.
The only tip that I want to mention is that some part of the state can be persisted in the URL and shouldn't be duplicated in the store.
Instead, you can make use of the selectors provided by @ngrx/router-store.

Registering the Store

Instead of creating a global application state, AppState in most cases, I prefer to not have a global state defined.
This has several benefits. The biggest one is that we can remove a layer of complexity, and keep all state levels equal.
Combining multiple slices of the state into a single object, being as a global state or feature state, is also a common source where things can get wrong (especially when using the older syntaxes we've covered above).

So why not avoid this complexity and keep things consistent?

To achieve this, register the global store in the root module, without providing a state.
Then, register each slice as a separate feature.

import { NgModule } from "@angular/core";
import { StoreModule } from "@ngrx/store";
import { customersReducer } from "./customers.reducer";
import { ordersFeature } from "./orders.feature";

@NgModule({
    imports: [
        // in NgRx 15 it isn't required to provide a state object
        StoreModule.forRoot(),
        // register the reducer
        StoreModule.forFeature("customers", customersReducer),
        // register the feature, this uses the feature name defined in createFeature
        StoreModule.forFeature(ordersFeature),
    ],
})
export class AppModule {}

We can then re-use the same pattern in the feature modules.

import { NgModule } from "@angular/core";
import { StoreModule } from "@ngrx/store";
import { shipmentFeature } from "./shipment.feature";

@NgModule({
    imports: [
      StoreModule.forFeature(shipmentFeature)
    ],
})
export class FeatureModule {}

In NgRx v15, there's a new way to register the Store when you're using the standalone components API.
With provideStore you can register the NgRx store (and register the root state), and with provideState you can provide feature states.

import { bootstrapApplication } from '@angular/platform-browser';
import { provideStore, provideState } from '@ngrx/store';
import { feature } from './feature.state';

bootstrapApplication(AppComponent, {
    providers: [
        provideStore(),
        provideState(feature)
    ];
})

And in a feature:

import { Routes } from '@angular/router';
import { provideState } from '@ngrx/store';
import { FeatureComponent } from './feature.component';
import { feature } from './feature.state';

export const routes: Routes = [
    {
        path: '',
        component: FeatureComponent,
        providers: [
            provideState(feature)
        ],
    },
];

Effects

You can take a look at the documentation to learn more about Effects.

Even if it's deprecated since NgRx v11, I still see projects that use the @Effect decorator.

Heads-up: the @Effect decorator is going to be removed in NgRx v15.

import { Injectable } from "@angular/core";
import { concatMap } from "rxjs";
import { Actions, Effect, ofType } from "@ngrx/effects";
import { CustomerPageActionTypes, CustomersLoaded } from "./customer.actions";

@Injectable()
export class CustomerEffects {
  @Effect()
  customerss$ = this.actions$.pipe(
    ofType<CustomersLoaded>(CustomerPageActionTypes.CustomersLoaded),
    concatMap(() => ...)
  );

  constructor(private actions$: Actions<CustomerPageActionTypes>) {}
}

This code snippet has multiple shortcomings.
First, an Effect should always return an action, using @Effect doesn't make sure of this.
Second, to have an effect that knows the signature of the handled action, either the Actions needs to be typed by providing the action union generic, or the ofType operator needs to use a generic of the handled action.

But, of course, we can do better with the updated API.
The above code can be refactored to use the createEffect method.
This solves both shortcomings of @Effect as it ensures that the effect returns an action (instead of all types), and the action is also automatically typed.

import { Injectable } from "@angular/core";
import { concatMap } from "rxjs";
import { Actions, createEffect, ofType } from "@ngrx/effects";
import { CustomerPageActions } from "./customer.actions";

@Injectable()
export class CustomerEffects {
  customers$ = createEffect(() => {
    // we use a body instead of a one-liner
    // this makes it easier to find errors in the RxJS stream
    // https://ngrx.io/guide/eslint-plugin/rules/prefer-effect-callback-in-block-statement
    return this.actions$.pipe(
      ofType(CustomerPageActions.CustomersLoaded),
      concatMap(() => ...)
    );
  });

  constructor(private actions$: Actions) {}
}

Notice that we don't need to provide a type to the injected Actions, nor to ofType operator.

In NgRx v15, there's a new way to register your Effects when you're using the standalone components API.
Instead of EffectsModule.forRoot([]) and EffectsModule.forFeature([]), there is the new provideEffects method that can be used to register your root and feature effects.

import { bootstrapApplication } from '@angular/platform-browser';
import { provideStore, provideState } from '@ngrx/store';
import { AppEffects } from './app.effects';

bootstrapApplication(AppComponent, {
    providers: [
        provideEffects(AppEffects),
    ];
})

And in a feature:

import { Routes } from '@angular/router';
import { provideState } from '@ngrx/store';
import { FeatureComponent } from './feature.component';
import { FeatureEffects } from './feature.effects';

export const routes: Routes = [
    {
        path: '',
        component: FeatureComponent,
        providers: [
            provideEffects(FeatureEffects),
        ],
    },
];

Injecting the Store

To select a slice of the state, or to dispatch an action, the Store instance needs to be injected.
In contrast to the first NgRx versions, when it was required to provide a state generic to the Store, this has become optional in NgRx v9.

If you're using selectors (which you should be), adding a generic only raises confusion and thus is considered as a bad practice.
Instead, simply inject the Store without a generic.

By doing this, you won't lose the type-safety NgRx provides, as the selectors provide the type-safety that is needed.

import { Component } from "@angular/core";
import { Store } from "@ngrx/store";
import { selectCustomers } from "./customer.selector";

@Component({
  selector: "app-customers",
  template: `...`,
})
export class CustomersComponent {
    customers$ = this.store.select(selectCustomers);

    constructor(private store: Store) {}
}

Component Store

It's important to know that not everything needs to be in the global store.
Sometimes it's better to keep the state local to the component.
This is where the Component Store, @ngrx/component-store, comes in.
For a comparison between the Component Store and the Global Store, and when to use which, take a look at the documentation.

Since the introduction of component-store in NgRx v9.2 not a lot has changed about its API, but the existing API have had a couple of small improvements.

The biggest improvement in NgRx v15, is that selectors can easily be combined into a model.

- readonly vm$ = this.select(
-     this.customers$,
-     this.selectedCustomer$,
-     this.orders$,
-     (
-         customers,
-         selectedCustomer,
-         orders,
-     ) => ({
-         customers,
-         selectedCustomer,
-         orders,
-     }),
- );

+ readonly vm$ = this.select({
+   customers: this.customers$,
+   selectedCustomer: this.selectedCustomer$,
+   orders: this.orders$,
+ });

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Watch out what you expose with Angular Interceptors

Tim Deschryver — Tue, 04 Oct 2022 16:57:56 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

You're probably already using Angular Interceptors.
Even if you can't find one in the application you're working in, there is a big chance that one of the added libraries makes use of an interceptor, especially if you're dealing with Authentication headers.

You can compare an Angular Interceptor with the entrance door of your favorite conference.
When you arrive at the conference you need go to through the entrance, and you can pick up some swag before entering the venue.
After the day is over and you want to exit the venue, you need to pass through the door again and you might pick up some more swag.

Going back to Angular interceptors, all HTTP requests that are initiated through the HTTP client are handled by the registered interceptors right before they're sent to the server, and again when the server answers with a response.
This makes interceptors the ideal place to put common logic to work with HTTP traffic.

Interceptors come in different flavors, and they're often responsible for a specific task.
For example, you can write an interceptor that acts as a caching layer, an interceptor that's responsible for showing and hiding a loader indicator, or another one to handle HTTP errors unanimously.
But, the most popular interceptor is the one that adds request headers to the HTTP request, for example adding an Authentication header to the request headers with the token of the user.

It's about these interceptors that I want to talk to you about.
A typical interceptor that does this is often implemented like one of the below.

From the Angular docs:

import { AuthService } from '../auth.service';

@Injectable()
export class AuthInterceptor implements HttpInterceptor {
    constructor(private auth: AuthService) {}

    intercept(req: HttpRequest<any>, next: HttpHandler) {
        // Get the auth token from the service.
        const authToken = this.auth.getAuthorizationToken();

        // Clone the request and replace the original headers with
        // cloned headers, updated with the authorization.
        const authReq = req.clone({
            headers: req.headers.set('Authorization', authToken),
        });

        // send cloned request with header to the next handler.
        return next.handle(authReq);
    }
}

From an article that comes as one of the first google results:

export class AuthInterceptorService implements HttpInterceptor {
    constructor(private authService: AuthService) {}
    intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
        const token = this.authService.getAuthToken();

        if (token) {
            // If we have a token, we set it to the header
            request = request.clone({
                setHeaders: { Authorization: `Authorization token ${token}` },
            });
        }

        return next.handle(request).pipe(
            catchError((err) => {
                if (err instanceof HttpErrorResponse) {
                    if (err.status === 401) {
                        // redirect user to the logout page
                    }
                }
                return throwError(err);
            }),
        );
    }
}

From the top Stack Overflow question and the corresponding answer:

import { Injectable } from '@angular/core';

import { HttpEvent, HttpInterceptor, HttpHandler, HttpRequest } from '@angular/common/http';

import { Observable } from 'rxjs/Observable';


@Injectable()
export class fwcAPIInterceptor implements HttpInterceptor {
  intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {

    const authReq = req.clone({
      headers: req.headers.set('Content-Type', 'application/json')
    });

    console.log('Intercepted HTTP call', authReq);

    return next.handle(authReq);
  }
}

const authReq = req.clone({
    headers: req.headers.set('Content-Type', 'application/json')
    .set('header2', 'header 2 value')
    .set('header3', 'header 3 value')
});

Do you notice what might go wrong here?

Let me give you a hint, what if the application sends an HTTP request to a 3rd party API?

Correct, then all the additional headers that are added by the interceptor are also sent to the 3rd party API.
Ideally, this shouldn't be happening, but when it does - by accident or not - you don't want to leak (sensitive) information to a 3rd party.

There are several solutions to prevent this from happening.
Let's take a look at them.

The easiest, and most secure, is verifying the host of the outgoing request.
Only when it's a trusted host, the headers are appended to the request.

When we apply this to the example of the Angular docs, the interceptor now looks like this.

import { AuthService } from '../auth.service';

@Injectable()
export class AuthInterceptor implements HttpInterceptor {
    constructor(private auth: AuthService) {}

    intercept(req: HttpRequest<any>, next: HttpHandler) {
        const uri = new URL(req.url);
        if(uri.hostname !== 'trusted-domain.com') {
            return next.handle(req);
        }

        // Get the auth token from the service.
        const authToken = this.auth.getAuthorizationToken();

        // Clone the request and replace the original headers with
        // cloned headers, updated with the authorization.
        const authReq = req.clone({
            headers: req.headers.set('Authorization', authToken),
        });

        // send cloned request with header to the next handler.
        return next.handle(authReq);
    }
}

A variant of the above solution is more flexible and uses a configurable collection of host names.

Because practice makes the check configurable, many libraries use this technique.
For example, the Angular Auth OIDC Client uses configurable secure routes to only append the Authorization header to requests that are sent to the configured host names (secure routes).

import { AuthService } from '../auth.service';
import { Config } from '../config';

@Injectable()
export class AuthInterceptor implements HttpInterceptor {
    constructor(private auth: AuthService, private config: Config) {}

    intercept(req: HttpRequest<any>, next: HttpHandler) {
        const uri = new URL(req.url);
        if(!config.trustedHostNames.includes(uri.hostname)) {
            return next.handle(req);
        }

        // Get the auth token from the service.
        const authToken = this.auth.getAuthorizationToken();

        // Clone the request and replace the original headers with
        // cloned headers, updated with the authorization.
        const authReq = req.clone({
            headers: req.headers.set('Authorization', authToken),
        });

        // send cloned request with header to the next handler.
        return next.handle(authReq);
    }
}

Another solution uses the HttpContext to ignore specific requests.
But, this makes it also easy to forget to add the context to a request, which is not ideal.

This looks as follows.

First define a HttpContextToken.

const IS_UNTRUSTED = new HttpContextToken<boolean>(() => false);

Then set the token for a request.

import { IS_UNTRUSTED } from './token.ts';

@Injectable()
export class Some3rdPartyService {
    constructor(private http: HttpClient) {}

    getData() {
        return this.http.get('3rd-party-api',
            {
                context: new HttpContext().set(IS_UNTRUSTED, true),
            }
        )
    }
}

Lastly, verify if the token is set in the interceptor.

import { AuthService } from '../auth.service';
import { IS_UNTRUSTED } from './token.ts';

@Injectable()
export class AuthInterceptor implements HttpInterceptor {
    constructor(private auth: AuthService) {}

    intercept(req: HttpRequest<any>, next: HttpHandler) {
        if (req.context.get(IS_UNTRUSTED)) {
            return next.handle(req);
        }

        // Get the auth token from the service.
        const authToken = this.auth.getAuthorizationToken();

        // Clone the request and replace the original headers with
        // cloned headers, updated with the authorization.
        const authReq = req.clone({
            headers: req.headers.set('Authorization', authToken),
        });

        // send cloned request with header to the next handler.
        return next.handle(authReq);
    }
}

Conclusion

All HTTP requests that are initiated by the HTTP client are intercepted by your Angular interceptors.
This is a powerful feature that allows you to add logic to all outgoing HTTP requests.

But, this makes it also easy to leak (sensitive) information to 3rd party APIs.
These requests are also intercepted by the same interceptors.
This way you can accidentally add more information to the request that you would want, even without knowing it.
The most common violation is adding an Authorization header to the requests.

As a best practice, always verify if the outgoing request is sent to a trusted host before appending headers to the request.

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Keep your Playwright tests structured with steps

Tim Deschryver — Thu, 25 Aug 2022 16:49:32 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Read the TLDR version on timdeschryver.dev

It's always useful to know why a test fails.
Ideally, we immediately see why (and which line(s)) causes the test to fail.
But this isn't always easy to know when you have a test that contains multiple steps.
This is where a good test runner helps you to win some time.

Dividing an end-to-end test into multiple steps is a popular practice because it makes the test cases faster to execute and because you probably built on top of the created/changed data.

For me, this is important because I like to write whole flows in an end-to-end test, this way I'm confident that everything works, but it's even helpful for simpler test cases.
Luckily, Playwright can give us a hand and can quickly point us toward the problem.

As an example, let's take a closer look at a Playwright example, which is generated as an example with the init command (npm init playwright).

👎 Code comments

The test case below isn't large, but it's already containing symptoms of a test that is not well-structured and hard to maintain.
As you can notice, the test case is divided into multiple steps.
Each step contains a comment to make the intent of the code block (a step) clear to the reader.

In these cases, a step can be compared to a smaller test case within the bigger test.

test('should allow me to mark items as complete', async ({ page }) => {
    // Create two items.
    for (const item of TODO_ITEMS.slice(0, 2)) {
        await page.locator('.new-todo').fill(item);
        await page.locator('.new-todo').press('Enter');
    }

    // Check first item.
    const firstTodo = page.locator('.todo-list li').nth(0);
    await firstTodo.locator('.toggle').check();
    await expect(firstTodo).toHaveClass('completed');

    // Check second item.
    const secondTodo = page.locator('.todo-list li').nth(1);
    await expect(secondTodo).not.toHaveClass('completed');
    await secondTodo.locator('.toggle').check();

    // Assert completed class.
    await expect(firstTodo).toHaveClass('completed');
    await expect(secondTodo).toHaveClass('completed');
});

Let's also take a look at the Playwright report for the test case.

We can see that all the user actions and asserts are added to the report.
It's even possible to expand them and to see the corresponding code.
This is fine when everything works, but let's see what the Playwright report looks like when the same test fails.

Looking at the Playwright report it's still clear why the test fails, which is "waiting for selector '.new-todo-fail'".
In other words, it can't find the .new-todo-fail selector.

There's even the line number with the code block that causes the test to fail.
While it's something, I don't find this ideal because we don't see the full context.
We have to open the test file manually to get the full picture of the test, for example, to know the steps before.

In this specific example, we don't know which to-do item caused the test to fail.
This might be a trigger for you to know what to do next in order to fix the failing test.

👎 Log statements

As a countermeasure for this problem, I usually see a lot of projects that add console.log statements to get more information.

So, let's include them in the test and see what happens.
In the following example, log statements are added to know which todo is created, and which todo is checked.

test('should allow me to mark items as complete', async ({ page }) => {
    // Create two items.
    for (const item of TODO_ITEMS.slice(0, 2)) {
        console.log('create todo', item);
        await page.locator('.new-todo').fill(item);
        await page.locator('.new-todo-fail').press('Enter');
    }

    // Check first item.
    const firstTodo = page.locator('.todo-list li').nth(0);
    await firstTodo.locator('.toggle').check();
    await expect(firstTodo).toHaveClass('completed');
    console.log('checked', TODO_ITEMS[0]);

    // Check second item.
    const secondTodo = page.locator('.todo-list li').nth(1);
    await expect(secondTodo).not.toHaveClass('completed');
    await secondTodo.locator('.toggle').check();
    console.log('checked', TODO_ITEMS[1]);

    // Assert completed class.
    await expect(firstTodo).toHaveClass('completed');
    await expect(secondTodo).toHaveClass('completed');
});

The test still fails when it's re-executed, but the added logs are now included in the Playwright report.

While this is better, I still don't find this to be ideal because the information is scattered.
We receive all the pieces, but we have to put the pieces together to get the full picture.

👍 Steps

So far, we've seen that code comments and log statements offer a way to better understand the test, but they aren't ideal.
The best solution in my opinion is to use the test.step function.

We can replace the comments and log statements, with the test.step function, which accepts two arguments.
The first argument is a description, and the second argument is a function that contains the code that we want to test.
This signature should be familiar, as it's almost identical to the test function.

The refactored test with steps looks like this.

test('should allow me to mark items as complete', async ({ page }) => {
    for (const item of TODO_ITEMS.slice(0, 2)) {
        await test.step(`Create todo ${item}`, async () => {
            await page.locator('.new-todo').fill(item);
            await page.locator('.new-todo-fail').press('Enter');
        });
    }

    await test.step(`Check first item`, async () => {
        const firstTodo = page.locator('.todo-list li').nth(0);
        await firstTodo.locator('.toggle').check();
        await expect(firstTodo).toHaveClass('completed');
    });

    await test.step(`Check second item`, async () => {
        const secondTodo = page.locator('.todo-list li').nth(1);
        await expect(secondTodo).not.toHaveClass('completed');
        await secondTodo.locator('.toggle').check();
    });

    await expect(firstTodo).toHaveClass('completed');
    await expect(secondTodo).toHaveClass('completed');
});

But the refactored test has a small problem because we don't have access to the firstTodo and secondTodo variables anymore.
To fix this, return the variables within the test.step function, and assign them to a variable.

test('should allow me to mark items as complete', async ({ page }) => {
    for (const item of TODO_ITEMS.slice(0, 2)) {
        await test.step(`Create todo ${item}`, async () => {
            await page.locator('.new-todo').fill(item);
            await page.locator('.new-todo-fail').press('Enter');
        });
    }

    const firstTodo = await test.step(`Check first item`, async () => {
        const firstTodo = page.locator('.todo-list li').nth(0);
        await firstTodo.locator('.toggle').check();
        await expect(firstTodo).toHaveClass('completed');
        return firstTodo;
    });

    const secondTodo = await test.step(`Check second item`, async () => {
        const secondTodo = page.locator('.todo-list li').nth(1);
        await expect(secondTodo).not.toHaveClass('completed');
        await secondTodo.locator('.toggle').check();
        return secondTodo;
    });

    await expect(firstTodo).toHaveClass('completed');
    await expect(secondTodo).toHaveClass('completed');
});

Now, when the test is executed, it results in the following Playwright report.

The Playwright report now includes the steps in detail, and we can easily find what caused the test to fail.

When we eventually fix the test, the Playwright report contains a nice summary of each step.

Conclusion

To summarize, we can replace comments and log statements with the test.step function.
By adding descriptive step descriptions it becomes easier to understand what is happening while reading the test case.

The steps also give a well-organized summary of the flow because these are included in the Playwright test report, which makes it easier to find the cause of the failure.
As a benefit, these reports can also be useful used while talking about the flow of the test.

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

New in Entity Framework 7: Bulk Operations with ExecuteDelete and ExecuteUpdate

Tim Deschryver — Thu, 18 Aug 2022 12:22:50 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Read the TLDR version on timdeschryver.dev

Version 7 of Entity Framework includes some popular features that have been asked for, one of which is Bulk Operations.
This feature came to my attention from a tweet by Julie Lerman, and I had to try it out for myself.

Why

So why is this feature needed if we already can update and delete entities?
The key word here is performance. This is a theme that has been on the top of the list when it comes to new EF versions, and this time it is no different.

The added methods improve the performance in multiple ways.
Instead of first retrieving the entities and having all the entities in memory before we can perform an action on them, and lastly committing them to SQL. We now can do this with just a single operation, which results in one SQL command.

Let's take a look at how this looks like in code.

Setting the stage

Before we dive into the examples, let's first set up our SQL database and populate 3 tables:

one to hold persons
another one is for addresses (a person has an address)
and the last one to store pets (a person has a collection of pets)

using Microsoft.EntityFrameworkCore;

using (var context = new NewInEFContext())
{
    SetupAndPopulate(context);
}

static void SetupAndPopulate(NewInEFContext context)
{
    context.Database.EnsureDeleted();
    context.Database.EnsureCreated();
    context.Persons.AddRange(Enumerable.Range(1, 1_000).Select(i =>
    {
        return new Person
        {
            FirstName = $"{nameof(Person.FirstName)}-{i}",
            LastName = $"{nameof(Person.LastName)}-{i}",
            Address = new Address
            {
                Street = $"{nameof(Address.Street)}-{i}",
            },
            Pets = Enumerable.Range(1, 3).Select(i2 =>
            {
                return new Pet
                {
                    Breed = $"{nameof(Pet.Breed)}-{i}-{i2}",
                    Name = $"{nameof(Pet.Name)}-{i}-{i2}",
                };
            }).ToList()
        };
    }));

    context.SaveChanges();
}

public class NewInEFContext : DbContext
{
    public DbSet<Person> Persons { get; set; }
    public DbSet<Pet> Pets { get; set; }
    public DbSet<Address> Addresses { get; set; }

    protected override void OnConfiguring(DbContextOptionsBuilder options)
        => options
            .UseSqlServer("Connectionstring");

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Address>()
           .Property<long>("PersonId");

        modelBuilder.Entity<Pet>()
            .Property<long>("PersonId");
    }
}

public class Person
{
    public long PersonId { get; set; }
    public string FirstName { get; set; } = "";
    public string LastName { get; set; } = "";
    public Address? Address { get; set; }
    public List<Pet> Pets { get; set; } = new List<Pet>();
}

public class Address
{
    public long AddressId { get; set; }
    public string Street { get; set; } = "";
}

public class Pet
{
    public long PetId { get; set; }
    public string Breed { get; set; } = "";
    public string Name { get; set; } = "";
}

`ExecuteDelete` and `ExecuteDeleteAsync`

Now that we got that out of our way, let's dive into ExecuteDelete and ExecuteDeleteAsync.

To delete a set of entities in bulk, filter out the entities that you want to delete by using the Where method (this is similar to before).
Then, invoke the ExecuteDelete method on the collection of entities to be deleted.

using (var context = new NewInEFContext())
{
    SetupAndPopulate(context);

    context.Pets
           .Where(p => p.Name.Contains("1"))
           .ExecuteDelete();
}

Let's also take a look at the SQL statement that this generates:

DELETE FROM [p]
FROM [Pets] AS [p]
WHERE [p].[Name] LIKE N'%1%'

As you can see, it simply generates one SQL statement to delete the entities that match the condition.
The entities also aren't kept in memory anymore.
Nice, simple, and efficient!

Cascade delete

Let's take a look at another example, and let's remove some people that hold references to addresses and pets.
By deleting the person, we also delete the address and pets because the delete statement cascades to the foreign tables.

using (var context = new NewInEFContext())
{
    SetupAndPopulate(context);

    context.Persons
           .Where(p => p.PersonId <= 500)
           .ExecuteDelete();
}

Similar to before, this results in the following SQL statement:

DELETE FROM [p]
FROM [Persons] AS [p]
WHERE [p].[PersonId] <= CAST(500 AS bigint)

Number of rows affected

It's also possible to see how many rows were affected by the delete operation, ExecuteDelete returns the number of rows affected.

using (var context = new NewInEFContext())
{
    SetupAndPopulate(context);

    var personsDeleted =
        context.Persons
           .Where(p => p.PersonId <= 100)
           .ExecuteDelete();
}

In the expression above, the personsDeleted variable is equal to 100.

`ExecuteUpdate` and `ExecuteUpdateAsync`

Now that we've seen how to delete entities, let's explore how to update them.
Just like ExecuteDelete, we first have to filter the entities that we want to update, and then invoke ExecuteUpdate.

To update entities we need to use the new SetProperty method.
The first argument of SetProperty selects the property that has to be updated via a lambda, and the second argument is the new value of that property also by using a lambda.

For example, let's set the last name of the persons to "Updated".

using (var context = new NewInEFContext())
{
    SetupAndPopulate(context);

    context.Persons
           .Where(p => p.PersonId <= 1_000)
           .ExecuteUpdate(p => p.SetProperty(x => x.LastName, x => "Updated"));
}

Which results in the corresponding SQL statement:

UPDATE [p]
    SET [p].[LastName] = N'Updated'
FROM [Persons] AS [p]
WHERE [p].[PersonId] <= CAST(1000 AS bigint)

We can also access the values of an entity and use that to create a new value.

using (var context = new NewInEFContext())
{
    SetupAndPopulate(context);

    context.Persons
           .Where(p => p.PersonId <= 1_000)
           .ExecuteUpdate(p => p.SetProperty(x => x.LastName, x => "Updated" + x.LastName));
}

Resulting in the following SQL statement:

UPDATE [p]
    SET [p].[LastName] = N'Updated' + [p].[LastName]
FROM [Persons] AS [p]
WHERE [p].[PersonId] <= CAST(1000 AS bigint)

Updating multiple values at once

We can even update multiple properties at once by invoking SetProperty multiple times.

using (var context = new NewInEFContext())
{
    SetupAndPopulate(context);

    context.Persons
           .Where(p => p.PersonId <= 1_000)
           .ExecuteUpdate(p =>
                p.SetProperty(x => x.LastName, x => "Updated" + x.LastName)
                 .SetProperty(x => x.FirstName, x => "Updated" + x.FirstName));
}

And again, the corresponding SQL statement:

UPDATE [p]
    SET [p].[FirstName] = N'Updated' + [p].[FirstName],
    [p].[LastName] = N'Updated' + [p].[LastName]
FROM [Persons] AS [p]
WHERE [p].[PersonId] <= CAST(1000 AS bigint)

Number of rows affected

Just like ExecuteDelete, ExecuteUpdate also returns the number of rows affected.

using (var context = new NewInEFContext())
{
    SetupAndPopulate(context);

    var personsUpdated =
        context.Persons
           .Where(p => p.PersonId <= 1_000)
           .ExecuteUpdate(p => p.SetProperty(x => x.LastName, x => "Updated"));
}

Note that updating nested entities is not supported.

More Updates in Entity Framework 7

For the complete list of new features, see the EF 7 plan.

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

How to upload files with Playwright

Tim Deschryver — Wed, 03 Aug 2022 17:30:48 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Read the TLDR version on timdeschryver.dev

This post shows you how to upload files with Playwright.
To keep it basic, let's just take a page with a simple upload input element, and let's also show the filename after it's been uploaded.

As usual, I start writing my Playwright test by starting the codegen tool.
Because I installed the Playwright extension for Visual Studio Code, I can quickly start the codegen tool via the command palette.

Let's take a look at the codegen tool in action to upload a file.

When we're done with the codegen tool, we end up with a new test file and the following generated code.
I already highlighted the most important lines.

import { test, expect } from '@playwright/test';

test('test', async ({ page }) => {

    // Go to http://127.0.0.1:8080/
    await page.goto('http://127.0.0.1:8080/');

    // Click input[name="file-upload"]
    await page.locator('input[name="file-upload"]').click();

    // Upload fixture.pdf
    await page.locator('input[name="file-upload"]').setInputFiles('fixture.pdf');

    // Click text=fixture.pdf
    await page.locator('text=fixture.pdf').click();

});

As we can see in the generated test, we can use the page.setInputFiles method to upload one or more files.

So far so good, but when you run the test, you probably get the following error.

npx playwright test

Running 1 test using 1 worker
  1) [chromium] › test-1.spec.ts:3:1 › test ========================================================

    Error: ENOENT: no such file or directory, stat 'C:\Users\timde\dev\playgrounds\playwright-demo\fixture.pdf'

The error says that the file that we want to upload doesn't exist.
If we take a closer, we can notice that the codegen tools only sets the filename of the uploaded file, not the path to the file.
Because of this, the file cannot be found while the test is running.

To fix this problem, change the test so that it uses a relative path (starting from the root of the project) to the file.

I like to create a fixtures folder inside the tests folder for generic files that I want to use in my tests.
Specific files for a test can be added right next to the test file, which makes it obvious that it's specific to a test.

The modified test looks like this.

import { test, expect } from '@playwright/test';

test('test', async ({ page }) => {

    // Go to http://127.0.0.1:8080/
    await page.goto('http://127.0.0.1:8080/');

    // Click input[name="file-upload"]
    await page.locator('input[name="file-upload"]').click();

    // Upload fixture.pdf
    await page.locator('input[name="file-upload"]').setInputFiles('./tests/fixtures/fixture.pdf');

    // Click text=fixture.pdf
    await page.locator('text=fixture.pdf').click();

});

After this change, the test passes.
More importantly, we've seen how to upload files with Playwright.

npx playwright test

Running 1 test using 1 worker

  1 passed (1s)

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Get access to the deployed Azure Static Webb App URL within your GitHub Workflow

Tim Deschryver — Fri, 29 Jul 2022 13:53:41 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Read the TLDR version on timdeschryver.dev

Hey you.
If you're here it probably means four things:

You're using an Azure Static Web App (SWA)
You're using GitHub Actions
You're deploying the SWA with the Azure/static-web-apps-deploy GitHub Action
You're looking into running your test suite (maybe with 🎭 Playwright) against a preview environment while a Pull Request is open

If this is you, you don't have to look any further because I got you covered!

When you create an Azure Static Web App within the Azure Portal and configure it to use GitHub with GitHub Actions, it automatically generates a GitHub workflow for you. The workflow file is also added to your GitHub repository, and it defines some pre-configured steps to build and deploy your SWA.

When I migrated my blog to be a SWA, the workflow that was generated looked like this:

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_SALMON_ROCK_0FB035B03 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "build" # Built app content directory - optional
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_SALMON_ROCK_0FB035B03 }}
          action: "close"

The workflow uses Azure/static-web-apps-deploy GitHub Action to build the application, and deploy it to your Azure resource.
The workflow is triggered when a pull request is opened, or when a push is made against the main branch.

What I was missing here is a way to make sure I don't break my blog when I make changes.
Believe me when I say that the timing is always bad when something is broken.
This happened to me numerous times in the past, especially because my blog is written with SvelteKit, which is undergoing changes regularly toward a stable v1 release.

I don't want to manually verify my blog I make changes because this can be time-consuming, and I always forgot something.
That's why I wanted to add a safety check within the workflow.
Automated tests to check if everything is working as expected.
Of course, I immediately grabbed to Playwright for this task.

Just like the GitHub workflow that was generated, Playwright is also able to create a workflow for you.
Just install Playwright with the init script, and work your way through the step wizard.

npm init playwright

When you've completed the wizard, you'll end up with a new GitHub workflow file.
In my case, this looked like the following file.

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v2
      with:
        node-version: '14.x'
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test
    - uses: actions/upload-artifact@v2
      if: always()
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

The workflow installs Playwright and executes the test suite when a push is made against the main branch, or when a Pull Request is opened.

To run these tests within my Azure workflow, I simply copy-pasted its content into the SWA workflow file, which gives the following result:

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_SALMON_ROCK_0FB035B03 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "build" # Built app content directory - optional
          ###### End of Repository/Build Configurations ######

  smoke_test_job:
    name: ☁️ Smoke test ${{ github.event.deployment_status.target_url }}
    runs-on: ubuntu-latest
    steps:
      - name: 🛎️ Checkout
        uses: actions/checkout@v3

      - name: 🔢 Use Node.js 16
        uses: actions/setup-node@v3
        with:
          node-version: 16

      - name: 🔎 Install dependencies
        run: npm install

      - name: 🎭 Install Playwright
        run: npx playwright install --with-deps

      - name: 🧪 Run Playwright Tests
        run: npm run test

      - name: 📦 Upload Test Results Artifact
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playwright-test-results
          path: playwright-report

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_SALMON_ROCK_0FB035B03 }}
          action: "close"

To get the most value out of these tests at this stage, you have to run them against the deployed environment.

Therefore, we need to know the deployed URL.
The docs mention there's a convention to build the preview URL, which looks like https://<SUBDOMAIN-PULL_REQUEST_ID>.<AZURE_REGION>.azurestaticapps.net. But this also doesn't take into account that we also have our live environment when we push to main. Ideally, we also want to verify
that this continues to work.

But there has to be a better way.
Luckily, there's the output variable static_web_app_url that's defined on the Azure/static-web-apps-deploy GitHub Action.

With this knowledge, all we have to do is include the static_web_app_url variable to the output variables of the build job. This way, we can access the variable within the test job to configure Playwright.
To run the Playwright tests against the preview environment, assign the output variable to the PLAYWRIGHT_TEST_BASE_URL environment variable within the test job.

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
+    outputs:
+      swa_url: ${{ steps.builddeploy.outputs.static_web_app_url }}
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_SALMON_ROCK_0FB035B03 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: 'upload'
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: '/' # App source code path
          api_location: '' # Api source code path - optional
          output_location: 'build' # Built app content directory - optional
          production_branch: 'main'
          ###### End of Repository/Build Configurations ######

  smoke_test_job:
    name: ☁️ Smoke test ${{ github.event.deployment_status.target_url }}
+    needs: build_and_deploy
    runs-on: ubuntu-latest
    env:
+      PLAYWRIGHT_TEST_BASE_URL: ${{ needs.build_and_deploy.outputs.swa_url }}
    steps:
      - name: 🛎️ Checkout
        uses: actions/checkout@v3

      - name: 🔢 Use Node.js 16
        uses: actions/setup-node@v3
        with:
          node-version: 16

      - name: 🔎 Install dependencies
        run: npm install

      - name: 🎭 Install Playwright
        run: npx playwright install --with-deps

      - name: 🧪 Run Playwright Tests
        run: npm run test

      - name: 📦 Upload Test Results Artifact
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playwright-test-results
          path: playwright-report

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_SALMON_ROCK_0FB035B03 }}
          action: 'close'

Now, with this change, no more faux-passes reach the live environment of my blog 🤞.
And if they do, I'm notified about it.

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Exploring the new output caching middleware

Tim Deschryver — Tue, 19 Jul 2022 17:42:26 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Caching in ASP.NET hasn't been great
yet, but this changes with the recent addition of the new output caching middleware that has landed
in .NET 7 Preview 6.

In this post, we're exploring the capabilities of the new output caching middleware and how to use it.
As an example, let's create a new API and add caching to the weather forecast endpoint.

Create a new API

Use the following command to create a new web API project.
To follow along with me, make sure you have at least
version 7.0.0-preview.6 installed.

dotnet new webapi -minimal -o OutputCachingExample

Enable Output Caching

To use the output caching middleware on top of your endpoint, you first need to register the OutputCache into your
application.
Do this by using the IServiceCollection.AddOutputCache and the IApplicationBuilder.UseOutputCache extension
methods while setting up the API in the Program.cs file.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

Add a caching layer to an endpoint

With the output caching middleware enabled we can start to add a caching layer on top of the endpoints of the API.
The most basic way to do this is by using the CacheOutput extension to an IEndpointRouteBuilder (a route).

In the following example, the /weatherforecast route is cached because we "marked" the route to be cached with CacheOutput.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.CacheOutput();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

The result is that the handler of the endpoint is invoked the first time it receives a request.
Then, when it receives new requests, the caching layer returns the cached response without executing the endpoint's
logic.

This is made visible in the next GIF, where a delay is added to the handler to make it clearer when the cache is empty, or when the cache is hit.

Cache by Query Parameter

Because a weather forecast is specific to a region, using a single cache doesn't make sense.
Let's see what happens when we add a query parameter "city" to request the weather forecast for a specific city.

In the example below, the city query parameter (with Brussels as value) is added to the URL which means that the handler of the endpoint is executed.
When the city value is changed (from Brussels to Paris), the handler is also invoked again.
Lastly, a second query parameter "other" is added to the URL, this also results that the handler is run again.

By testing this out we learn that the default behavior uses the URL path with query parameters to identify unique requests, and also to read and write to the cache.
When the value of a query parameter changes or when a new query parameter is added, the cache isn't hit.
If this isn't the desired behavior, the configuration of the output cache can be fine-tuned to your needs.

To cache a request by a (or multiple) unique query parameter(s), use the overload of CacheOutput.
The overload gives us access to the policy builder OutputCachePolicyBuilder to configure the caching strategy.

One of the options is to use the OutputCachePolicyBuilder.VaryByQuery method to uniquely identify requests by specific query parameter(s). The method expects none, one, or multiple query parameter names to vary the cache.

Let's see what happens when we configure the policy to identify requests by the "city" query parameter.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.CacheOutput(p => p.VaryByQuery("city"));

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

To completely ignore query parameters within the URL, use OutputCachePolicyBuilder.VaryByQuery but leave the query parameters empty.

app.MapGet("/weatherforecast", async () =>
{
    // handler logic here
})
.CacheOutput(p => p.VaryByQuery());

This gives us the following result.

Cache by Request Header

Instead of using query parameters, you can also build the cache with request headers with OutputCachePolicyBuilder.VaryByHeader.
In the following example, the "X-City" request header differentiates requests by city, each city has an individual cache.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.CacheOutput(p => p.VaryByHeader("X-City"));

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Cache by Value

You can make use of OutputCachePolicyBuilder.VaryByValue to even have more fine-grained control over the cache policy.
OutputCachePolicyBuilder.VaryByValue is a Func that takes the HttpContext as argument and expects a string
or KeyValuePair<string, string> as result.

I haven't had the need to implement a cache using this, if you have a good use case feel free to contact me.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.CacheOutput(x => x.VaryByValue(httpCtx => {
    /*
     * Implementation here
     */
}));

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Cache Expiration

The default implementation expires the cache after one minute (absolute duration).

To control how long a cache entry is valid, set expiration for routes by using the OutputCachePolicyBuilder.Expire method and pass it a TimeSpan.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.CacheOutput(p => p.Expire(TimeSpan.FromSeconds(2)));

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Modify the default expiration time

To change the default expiration time, update the DefaultExpirationTimeSpan while registering the Output Cache.
For example, to use the cache for one hour:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache(options =>
{
    options.DefaultExpirationTimeSpan = TimeSpan.FromHours(1);
});

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

Cache Purge

In some cases, you might want to purge (clear) the cache when a certain event occurs.
For example, when you know that the data has been updated, and you want to provide your users the updated data.
When the cache is purged, the cache is revalidated when the next request is received.

To purge the cache, first, add a tag (which is a string) to the cache output with the OutputCachePolicyBuilder.Tag method.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.CacheOutput(p => p.Tag("wf"));

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Then, inject the IOutputCacheStore store and call the EvictByTagAsync method.
The method accepts the tag name that needs to be purged.

public class SomeClass
{
    private readonly IOutputCacheStore _cache;

    public SomeClass(IOutputCacheStore cache)
    {
        _cache = cache;
    }

    public  async Task SomeMethod(CancellationToken cancellationToken)
    {
        // Some logic here....
        await _cache.EvictByTagAsync("wf", cancellationToken);
    }
}

RouteGroups

Now that we've seen how the basics of the CacheOutput middleware works, let's see how to use it in more complex scenarios.

When you have multiple endpoints that require a cache with similar policies, you don't have to add the CacheOutput middleware to each endpoint. This would be hard to maintain, and easy to make mistakes.
To make it better manageable, create a route group and add the middleware to the group.

In the example below we first create a route group called wf, and apply the output cache middleware to it.
Then, two endpoints are added to the group.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

var wf = app.MapGroup("weatherforecast").CacheOutput();

wf.MapGet("", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
});

wf.MapGet("other", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
});

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Disable caching with NoCache

When working with groups (or policies later), the configuration that is applied on individual endpoints takes precedence over the configuration that is applied to the group.

For example, if you don't want to cache an endpoint, you can use the OutputCachePolicyBuilder.NoCache method.
In the example below, the /nocache route is added to the wf group that was created in the previous step.
The NoCache is applied to the /nocache route, because of this, this route won't use the cache policies that were applied on the wf group.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

var wf = app.MapGroup("weatherforecast").CacheOutput();

wf.MapGet("", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
            new WeatherForecast
            (
                DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                Random.Shared.Next(-20, 55),
                summaries[Random.Shared.Next(summaries.Length)]
            ))
        .ToArray();
    return forecast;
});

wf.MapGet("nocache", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
            new WeatherForecast
            (
                DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                Random.Shared.Next(-20, 55),
                summaries[Random.Shared.Next(summaries.Length)]
            ))
        .ToArray();
    return forecast;
})
.CacheOutput(p => p.NoCache());

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Policies

When you find yourself configuring many endpoints and/or endpoint groups with the same configuration, creating your own cache policy is probably the best way to go. While creating custom policies you can choose to create a named policy or to add a default policy to the whole application.

You can include your own custom policies within the callback of IServiceCollection.AddOutputCache.

Named policies

In the next example, the named cache policy InvariantQueries is created to ignore all query parameters.
This is done with the AddPolicy, which expects a policy name (a string), and an Action<OutputCachePolicyBuilder> to configure the cache policy.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache(options =>
{
    options.AddPolicy("InvariantQueries", builder =>
    {
        builder.VaryByQuery();
    });
});

To make use of the InvariantQueries policy, use another overload on the CacheOutput middleware and pass it the name of the policy. In our example, InvariantQueries.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache(options =>
{
    options.AddPolicy("InvariantQueries", builder =>
    {
        builder.VaryByQuery();
    });
});

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", async () =>
{
    await Task.Delay(1000);
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.CacheOutput("InvariantQueries");

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Default (or "Base") policies

To create a default policy that is used for all requests, use AddBasePolicy.
The difference with a named policy is that AddBasePolicy doesn't expect a policy name as an argument.
Just like a named policy, AddBasePolicy uses the Action<OutputCachePolicyBuilder> to configure the cache policy.

In the implementation of the example below all requests are cached if they contain the X-Cached header.
Notice that it isn't required to add CacheOutput to a route to enable this base policy.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder =>
    {
        builder.With(p => p.HttpContext.Request.Headers.ContainsKey("X-Cached"));
    });
});

var app = builder.Build();
app.UseHttpsRedirection();
app.UseOutputCache();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
});

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Cache locking

When a cache entry doesn't exist and needs to be created, but the server receives multiple requests simultaneously for that entry, then the handler is only executed once. The handler of the first request populates the cache, and the other requests wait until the first request is finished. This prevents the server from being overloaded with requests.

The DefaultPolicy implementation

To know how the default implementation behaves, you can take a look at the source code of DefaultPolicy.

One detail that pops out, and which I didn't expect at first but makes sense, is the check if output caching should be used.
Here, we can see that authorized requests are ignored from being cached.

private static bool AttemptOutputCaching(OutputCacheContext context)
{
    // Check if the current request fulfills the requirements to be cached

    var request = context.HttpContext.Request;

    // Verify the method
    if (!HttpMethods.IsGet(request.Method) && !HttpMethods.IsHead(request.Method))
    {
        context.Logger.RequestMethodNotCacheable(request.Method);
        return false;
    }

    // Verify existence of authorization headers
    if (!StringValues.IsNullOrEmpty(request.Headers.Authorization) || request.HttpContext.User?.Identity?.IsAuthenticated == true)
    {
        context.Logger.RequestWithAuthorizationNotCacheable();
        return false;
    }

    return true;
}

If this doesn't work for your application, you can create your own policy by implementing the IOutputCachePolicy interface.
The created policy then has to be provided to AddBasePolicy.

Using OutputCache with Controllers

So far we've only seen how to use the OutputCache middleware with minimal APIs.

But, because it's just a middleware it can also be used with the traditional controllers.
As you can see in the example below, you simply have to add the OutputCache attribute on top of the controller's method.
Or, when you want to enable output caching for the whole controller, you can add the OutputCache attribute to the controller class.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.OutputCaching;

namespace OutputCaching.Controllers;

[ApiController]
[Route("[controller]")]
[OutputCache] // enable caching for the whole controller
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    [HttpGet]
    [OutputCache] // enable caching for a specifc endpoint
    public async Task<IEnumerable<WeatherForecast>> Get()
    {
        await Task.Delay(1000);
        var forecast = Enumerable.Range(1, 5).Select(index =>
            new WeatherForecast
            (
                DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                Random.Shared.Next(-20, 55),
                Summaries[Random.Shared.Next(Summaries.Length)]
            ))
            .ToArray();
        return forecast;
    }
}

Conclusion

In this post, we've covered most of the features of the new output caching middleware.
Using the middleware improves the performance of your application.
Looking at the API, we've seen that it almost requires no code to use the caching middleware, while it's flexible to be configured to your own needs.

For more context, see the GitHub issue that discusses the new output caching middleware. For more examples, you can also take a look at the OutputCachingSample.

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Feature Flags in .NET, from simple to more advanced

Tim Deschryver — Wed, 22 Jun 2022 10:40:00 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Before we get to the actual content of this post, let's first talk about the concept of feature flags.
A feature flag is a way to enable or disable a feature, or code path within an application.

Ideally, "the switch" when you turn a feature on or off shouldn't have an effect on the code, nor should it require a new release of the code. It's just a toggle that you can flip on or off via some kind of configuration.

This can come in various forms:

a condition based on the environment, to enable a feature during Q&A, while disabling it in production until it's ready for production;
a feature that needs to be rolled out to a specific user, or user group, e.g. to testers;
a time-based feature that needs to be rolled out in the future, or for a certain amount of time, for example, to show a banner;
let the client decide if the feature is enabled or not, based on the user's preferences;

What I like about feature flags in the .NET ecosystem, is that you can start out simple and then add more to it when you need it. As you see later on in this blog post, the most useful feature flags are already implemented and you just have to plug them in.

Now, let's implement a naive feature flag in .NET and extend it to end up with a more robust solution.

Setting the stage

To follow along with me, create a new application with the following commands.

dotnet new webapi -minimal -o FeatureFlagsInNet
cd .\FeatureFlagsInNet

Next, open the application in your IDE and open the Program.cs file.
Here you'll find code that already implements a GET endpoint to retrieve a collection of weather forecasts.

A trimmed-down version of the code, with only the essentials (the swagger implementation is removed), looks like this.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();
app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();

    return Results.Ok(forecast);
});

app.Run();

record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

To verify that the current setup works, run the application and navigate to https://localhost:{portnumber}/weatherforecast (don't forget to update the port number).

dotnet watch run

If everything went well, you should see a collection of forecasts.
For me, this gives me the following result.

[
    {
        "date": "2022-06-18T14:38:57.4853538+02:00",
        "temperatureC": -4,
        "summary": "Freezing",
        "temperatureF": 25
    },
    {
        "date": "2022-06-19T14:38:57.4853797+02:00",
        "temperatureC": -7,
        "summary": "Scorching",
        "temperatureF": 20
    },
    {
        "date": "2022-06-20T14:38:57.48538+02:00",
        "temperatureC": -10,
        "summary": "Cool",
        "temperatureF": 15
    },
    {
        "date": "2022-06-21T14:38:57.4853802+02:00",
        "temperatureC": -9,
        "summary": "Mild",
        "temperatureF": 16
    },
    {
        "date": "2022-06-22T14:38:57.4853804+02:00",
        "temperatureC": 20,
        "summary": "Bracing",
        "temperatureF": 67
    }
]

Implementing a basic feature flag

With everything ready, we can start to implement a feature flag in the weather forecasts endpoint.

To keep things simple, let's say that the endpoint is enabled or disabled based on the flag.

The most basic feature flag is a simple if statement based on a boolean condition.

To implement the feature flag, define a forecastEnabled variable.
This variable's value decides the return value of the endpoint, when:

true (feature flag is enabled), the endpoint returns the forecast data;
false (feature flag is disabled), the endpoint returns a not found (404) status code;

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();
app.UseHttpsRedirection();

var forecastEnabled = true;
var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot"
};

app.MapGet("/weatherforecast", () =>
{
    if(!forecastEnabled) {
        return Results.NotFound();
    }

    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();

    return Results.Ok(forecast);
});

app.Run();

record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Configurable feature flag

So far, this doesn't really make sense.
The feature flag is either enabled or disabled for all of the clients.
To enable the forecasts endpoint, the forecastEnabled variable needs to be changed in code, and the application needs to be re-released.

Having to do this defeats the reasons why feature flags are useful.
The first step that needs to be taken to make this feature flag useful, is to find a way to dynamically change its value.

To achieve this, the feature's condition needs to be defined outside of the application code.
As the result, it allows us to change the setting during a release, and thus can the build artifact can be reused in multiple stages of the CI/CD pipeline.

An example: the feature flag can be enabled for a staging environment, while it can be disabled for a production environment.

A way to configure the feature flag conditions is to use the appsettings.
Therefore, we add an extra section FeatureFlags, within the section we also create the WeatherForecast property.

{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*",
    "FeatureFlags": {
        "WeatherForecast": true
    }
}

To use the newly introduced configuration, replace the forecastEnabled variable with the value from the appsettings.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();
app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot"
};

app.MapGet("/weatherforecast", () =>
{
    if (!builder.Configuration.GetValue<bool>("FeatureFlags:WeatherForecast"))
    {
        return Results.NotFound();
    }

    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();

    return Results.Ok(forecast);
});

app.Run();

record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Introducing standards with the Feature Management package

Instead of defining our own standards, we can also use Microsoft's implementation from the Microsoft.FeatureManagement.AspNetCore NuGet package.

To install the package, run the following command.

dotnet add package Microsoft.FeatureManagement.AspNetCore

After the package is installed, we can refactor our custom implementation with the generic implementation.
To do this:

import the Microsoft.FeatureManagement namespace;
register the AddFeatureManagement service;
inject the IFeatureManager into the endpoint;
use the IFeatureManager.IsEnabledAsync method to check if the feature is enabled;

using Microsoft.FeatureManagement;

var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddFeatureManagement(builder.Configuration.GetSection("FeatureFlags"));

var app = builder.Build();
app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot"
};

app.MapGet("/weatherforecast", async (IFeatureManager manager) =>
{
    if (!await manager.IsEnabledAsync("WeatherForecast"))
    {
        return Results.NotFound();
    }

    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();

    return Results.Ok(forecast);
});

app.Run();

record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

The configuration within the appsettings.json file doesn't need to be changed and can be reused as-is.
This step doesn't seem to be a big change, but it gives us the opportunity to do more...

Built-in filters

Besides a defined and consistent way to configure the feature flags, the package also provides a couple feature flag implementations (filters) for the most common scenarios.

With the Feature Management package, we can enable or disable a feature flag (true or false), just like before.
But the package also has a "filters" concept. With filters, a feature flag can be on or off based on certain conditions.
Each filter has its configuration schema (in JSON), but the way we verify that the feature is enabled remains the same for all filters.

In addition to the built-in filters, you can also write your own custom implementations.

The following filters are available:

PercentageFilter, to randomly enable/disable the feature based on a percentage;
TimeWindowFilter, to enable the feature during a predefined window with a start and end time;
TargetingFilter, to enable the feature for a specific user, or group of users (for this filter, a percentage can also be set);

For more info about these, you can take a look at the docs.

Important: As far as I know, the TargetingFilter filter cannot be used when the Minimal API structure is used. When you register the filter, you'll receive the error: System.InvalidOperationException: Unable to resolve service for type 'Microsoft.FeatureManagement.FeatureFilters.ITargetingContextAccessor' while attempting to activate 'Microsoft.FeatureManagement.FeatureFilters.TargetingFilter'.

These filters are available from the Microsoft.FeatureManagement.FeatureFilters namespace and must be registered individually.

The rest of the code remains the same.
In other words, this doesn't change how we verify that the feature flag is enabled.

using Microsoft.FeatureManagement;
using Microsoft.FeatureManagement.FeatureFilters;

var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddFeatureManagement(builder.Configuration.GetSection("FeatureFlags"))
    .AddFeatureFilter<PercentageFilter>()
    .AddFeatureFilter<TimeWindowFilter>();

var app = builder.Build();
app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot"
};

app.MapGet("/weatherforecast", async (IFeatureManager manager) =>
{
    if (!await manager.IsEnabledAsync("WeatherForecast"))
    {
        return Results.NotFound();
    }

    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();

    return Results.Ok(forecast);
});

app.Run();

record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

As said before, while the way we consume the feature flags remains the same, the way we configure them is different.

As you can see below, the type of filter is appointed with the Name property.
With the Parameters property, the configuration of the filter is set for the percentage and the time window filters.

{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*",
    "FeatureFlags": {
        "WeatherForecastPercentage": {
            "EnabledFor": [
                {
                    "Name": "Microsoft.Percentage",
                    "Parameters": {
                        "Value": 50
                    }
                }
            ]
        },
        "WeatherForecastTimeWindow": {
            "EnabledFor": [
                {
                    "Name": "Microsoft.TimeWindow",
                    "Parameters": {
                        "Start": "Mon, 06 Jun 2022 00:00:00 GMT",
                        "End": "Mon, 13 Jun 2022 00:00:00 GMT"
                    }
                },
                {
                    "Name": "Microsoft.TimeWindow",
                    "Parameters": {
                        "Start": "Mon, 04 Jul 2022 00:00:00 GMT",
                    }
                },
                {
                    "Name": "Microsoft.TimeWindow",
                    "Parameters": {
                        "End": "Mon, 11 Jul 2022 00:00:00 GMT"
                    }
                },
            ]
        }
    }
}

An example configuration for the targeting filter is shown below.
Instead of the Parameters property, the filter is configured with the Audience property.

{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*",
    "FeatureFlags": {
        "WeatherForecastTargeting": {
            "EnabledFor": [
                {
                    "name": "Microsoft.Targeting",
                    "parameters": {
                        "Audience": {
                            "Users": ["username1", "username2"],
                            "Groups": [
                                {
                                    "Name": "BetaUsers",
                                    "RolloutPercentage": 100
                                },
                                {
                                    "Name": "Internal",
                                    "RolloutPercentage": 75
                                }
                            ],
                            "DefaultRolloutPercentage": 0
                        }
                    }
                }
            ]
        }
    }
}

Writing a Custom Filter Implementation

To implement your own filter logic, create a class that implements the IFeatureFilter interface and register the service.

The IFeatureFilter interface lets you implement the EvaluateAsync method.
Here, you must write your own logic to determine if the feature is enabled or not.

The method receives the FeatureFilterEvaluationContext argument, which contains the configuration object.
To have access to the filter's parameters, use the FeatureFilterEvaluationContext.Parameters.Get<T>() method.

using Microsoft.FeatureManagement;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddFeatureManagement(builder.Configuration.GetSection("FeatureFlags"))
    .AddFeatureFilter<MyCustomFilter>();

var app = builder.Build();

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot"
};

app.MapGet("/weatherforecast", async (IFeatureManager manager) =>
{
    if (!await manager.IsEnabledAsync("WeatherForecast"))
    {
        return Results.NotFound();
    }

    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();

    return Results.Ok(forecast);
});

app.Run();

record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

[FilterAlias(nameof(MyCustomFilter))]
public class MyCustomFilter : IFeatureFilter
{
    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext evaluationContext, CancellationToken cancellationToken = default)
    {
        var settings = evaluationContext.Parameters.Get<MyCustomFilterSettings>()
            ?? throw new ArgumentNullException(nameof(MyCustomFilterSettings));
        return Task.FromResult(settings.LuckyNumber == 47);
    }
}

public class MyCustomFilterSettings
{
    public int LuckyNumber { get; set; }
}

Via the FilterAlias attribute, the name of the filter is set.
This is the same name that needs to be used within the configuration to couple the configuration to the filter.

{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*",
    "FeatureFlags": {
        "WeatherForecast": {
            "EnabledFor": [
                {
                    "name": "MyCustomFilter",
                    "parameters": {
                        "LuckyNumber": 47
                    }
                }
            ]
        }
    }
}

Using Parameters within Custom Filters

A filter can also receive parameters that are only known at runtime.
This could, for example, be an alternative to the TargetingFilter filter for minimal Apis, because it could receive the HTTP context or subset from it.

To create filters with parameters, replace the IFeatureFilter with the IContextualFeatureFilter interface.
After this change, the EvaluateAsync method receives the additional parameters.

In the example below, a header is read and passed to the filter, but this could also be the HttpContext, a ClaimsPrinciple, or something else.

using Microsoft.AspNetCore.Mvc;
using Microsoft.FeatureManagement;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddFeatureManagement(builder.Configuration.GetSection("FeatureFlags"))
    .AddFeatureFilter<MyCustomFilter>();

var app = builder.Build();

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot"
};

app.MapGet("/weatherforecast", async (IFeatureManager manager, [FromHeader(Name = "X-Lucky-Number")] int? inputNumber) =>
{
    if (!await manager.IsEnabledAsync("WeatherForecast", new MyCustomFilterContext { InputNumber = inputNumber ?? 0 }))
    {
        return Results.NotFound();
    }

    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();

    return Results.Ok(forecast);
});

app.Run();

record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

[FilterAlias(nameof(MyCustomFilter))]
public class MyCustomFilter : IContextualFeatureFilter<MyCustomFilterContext>
{
    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext evaluationContext, MyCustomFilterContext context, CancellationToken cancellationToken = default)
    {
        var settings = evaluationContext.Parameters.Get<MyCustomFilterSettings>()
            ?? throw new ArgumentNullException(nameof(MyCustomFilterSettings));
        return Task.FromResult(settings.LuckyNumber == context.InputNumber);
    }
}

public class MyCustomFilterSettings
{
    public int LuckyNumber { get; set; }
}

public class MyCustomFilterContext
{
    public int InputNumber { get; set; }
}

FeatureGate for MVC Controllers

This part is only available if your application is built by using controllers, and not with the Minimal Api structure.

Instead of checking if a feature is enabled within the code, you can use the FeatureGate attribute to disable a whole controller or a specific endpoint. The parameter passed to the attribute is the name of the feature that's set in the configuration.

using Microsoft.FeatureManagement.Mvc;

[FeatureGate("WeatherForecast")]
public class WeatherForecastController : ControllerBase
{
}

using Microsoft.FeatureManagement.Mvc;

public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    [FeatureGate("WeatherForecast")]
    public async IActionResult Get()
    {
    }
}

Azure Feature Management

So far, so good, but we can do better.

The current implementation has one drawback.
When the configuration is changed the application needs to be restarted to have an effect.
This has an impact on the users.

If you want to modify a feature flag without restarting the application, you can use the Feature Management feature from Azure.
This allows us to dynamically change the configuration of the feature flags.

Read the docs on how to install and manage the feature flags in Azure (pricing table).

In the Azure Portal, you can create and remove feature flag definitions, and configure their filters.
This is similar to what we had in the appsettings.json file, but it now has a user interface.

As an example, see the following screenshot that defines the WeatherForecast feature flag within the Azure Portal.
You can also notice that a label can be added to the feature flags, this is useful to create groups of features.

The configuration view of the feature flag looks like this:

To use the Azure Feature Management in code, first install the needed NuGet packages.

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore
dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

Before we can use the Azure Feature Management, we first need to configure the Azure App Configuration.
During the configuration, we connect to the specified Azure resource and enable the feature flags to feature.
While we do that, we also have the option to define which feature flags need to be registered based on their label.

The Azure Configuration can further be tweaked to fit your needs, e.g. set the cache duration, for more information about all the options sees the docs.

In the example below, we read all the feature flags that don't have a label defined, and also the feature flags for the current environment. The order is important here because the latter overrides the former.
Using this approach makes it easy to enable features for all environments (feature flags without a label), except for the production environment (feature flags with "Production" as the label).

While using the Azure Feature Management, don't forget to register the feature flag management feature, and the filters that are used, just as before in the previous examples that aren't using Azure.

using Microsoft.FeatureManagement;
using Microsoft.FeatureManagement.FeatureFilters;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((config, appBuilder) =>
{
    appBuilder.AddAzureAppConfiguration(azureConfig =>
    {
        azureConfig
            .Connect("Endpoint=https://name.azconfig.io;Id=id")
            // include all settings without a label
            .Select(KeyFilter.Any, LabelFilter.Null)
            // include all settings with the label that corresponds to the current environment
            // this overrides the previous setting if there are any
            .Select(KeyFilter.Any, config.HostingEnvironment.EnvironmentName);
        azureConfig.UseFeatureFlags();
    });
});.

builder.Services.AddAzureAppConfiguration();

builder.Services
    .AddFeatureManagement()
    .AddFeatureFilter<PercentageFilter>();

var app = builder.Build();

app.UseAzureAppConfiguration();
app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot"
};

app.MapGet("/weatherforecast", async (IFeatureManager manager) =>
{
    if (!await manager.IsEnabledAsync("WeatherForecast"))
    {
        return Results.NotFound();
    }

    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();

    return Results.Ok(forecast);
});

app.Run();

record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

As the last step, the feature settings from the appsettings.json file can be removed, Azure is now the owner of it.

Conclusion

In this post, we started off with a naive approach to implementing a feature flag.
It required us to recompile and redeploy the application in order to change the application's behavior.

The first step towards a better solution was to refactor the implementation by relocating the feature flag configuration from the code into the appsettings.json file. As result, the feature flag was declarative and the application could be redeployed (with a different behavior) without recompiling it and thus making it easy to turn off certain features in a specified environment. As a side-effect, the application now also meets the criteria of a twelve-factor app.

To introduce a standard the next step was to use the .NET Feature Management Api.
An additional benefit of using the Feature Management Api is that we have the possibility to target specific users.
Beyond only having an application-wide feature flag, a feature flag can be configured based on different conditions.
This feature is called a "filter", and the Feature Management Api has three filters built-in, the PercentageFilter, TimeWindowFilter, and TargetingFilter filters

What I like the most about the Feature Management Api is that it doesn't require us to change the way how we verify if a feature flag is enabled or not in code, because everything is done by having a configuration.

Lastly, to give us maximum flexibility, the Azure Feature Management was added.
Instead of storing the configuration in the appsettings.json file, the feature flags are now managed within the Azure Portal.
We now aren't obligated to restart the application when we make changes to the configuration before those changes take effect.
After making changes to the configuration, the application automatically updates at run-time via the dynamic configuration.

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Tye, starting and running multiple APIs with a single command

Tim Deschryver — Wed, 01 Jun 2022 16:10:47 +0000

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

Today, most of the applications consist of multiple projects.
Most of them have some kind of front-end application (e.g. Angular) that consumes one or more .NET C# APIs, which in their turn might also be linked to each other.

Because applications are built like this, running your local development environment can become a lot of work, and the environment also needs to be maintained.
When there goes something wrong while spinning up the environment, for example, an API that isn't started, it can be hard to find the cause of the problem. This is time that is wasted.
Your local environment might even take up a lot of resources when you have multiple Visual Studio or Rider instances open. Again, this is time that is wasted.

Thanks to the Project Tye this doesn't have to become a problem.
The best thing is you aren't required to learn anything new, and you can get up and running in just a few minutes. Besides being easy to use, another benefit is that Tye contains a few utilities that can be used to help you with your development.

Tye is a tool that makes developing, testing, and deploying microservices and distributed applications easier. Project Tye includes a local orchestrator to make developing microservices easier and the ability to deploy microservices to Kubernetes with minimal configuration.

In this post, we're applying the Pareto Principle(80/20 rule) to discover how easy it is to set up Tye. By following this rule, our team can run our whole local environment with just a single command.

In the short run, using Tye just seems like an improvement to your developer experience.
On its own, this already sounds like a good thing but in the long run, you'll also notice that a lot of time is saved.

Installation

Tye is installed as a global dotnet tool with the following command.
For more info, take a look at the Getting Started guide.

dotnet tool install -g Microsoft.Tye --version "0.11.0-alpha.22111.1"

Configuring your environment

When Tye is installed, create a tye.yml file and start to configure your environment.

Do this by including your .NET projects to the services section.
A service has a reference to the csproj file that needs to be started.
Optionally, create a binding (ignore this if the port doesn't matter, tye randomly assigns an available port when the binding isn't specified) for this service.

name: Awesome Application
services:
  - name: backend-one
    project: ./BackendOne/BackendOne.csproj
    bindings:
      - protocol: https
        port: 4061

  - name: backend-two
    project: ./BackendTwo/BackendTwo.csproj
    bindings:
      - protocol: https
        port: 5063

As mentioned before, Tye is focused on the .NET ecosystem but you can also include different technologies, for example, an Angular front-end application.
To do so, add the Angular application to your configuration as an executable.
To start the Angular application, define the script to run the application.

name: Awesome Application
services:
  - name: backend-one
    project: ./BackendOne/BackendOne.csproj
    bindings:
      - protocol: https
        port: 4061

  - name: backend-two
    project: ./BackendTwo/BackendTwo.csproj
    bindings:
      - protocol: https
        port: 5063

  - name: front-end
    executable: cmd
    args: '/c cd ./Frontend && npm run start'
    bindings:
      - protocol: https
        port: 4200

As shown below, you can also add a reference to a different repository that contains a tye config.

name: Awesome Application
services:
  ...

  - name: other repository
    include: ../other-repository/tye.yaml

Instead of the whole environment, it might be useful to solely run a subset of the environment.
Therefore, define tags within the configuration to filter the services.

name: Awesome Application
services:
  - name: backend-one
    project: ./BackendOne/BackendOne.csproj
    tags:
      - subset-one
    bindings:
      - protocol: https
        port: 4061

  - name: backend-two
    project: ./BackendTwo/BackendTwo.csproj
    tags:
      - subset-two
    bindings:
      - protocol: https
        port: 5063

Running the environment

Once your environment is configured, you can run it with the tye run command.

# runs `tye.yml` by default
tye run

# restart the service on file change
tye run --watch

# run a subset of services
tye run --tags subset-one

# provide a custom configuration file
tye run other-tye.yml

After running the command, the hosted environment (with logs) is visible in the Tye dashboard.
Navigate to http://localhost:8000 to open the dashboard.

How to debug services

Without using Tye, you probably started the API service manually by clicking on the Start button.
Doing this automatically hooked the debugger to the spawned process.

If you're using Tye, debugging is isn't automatically anymore.
Instead, you have to attach your IDE to the spawned process when you want to start a debug session.

Bonus tip

I like to be able to run my environment with a single command, no matter in which directory I'm currently in.
Therefore, I've added a shortcut to my PowerShell profile.
The profile executes the tye command and provides it the full path of the config.

tye run "C:\Users\timde\dev\project\tye.yaml" --watch

Summary

Tye is installed as a global dotnet tool
The environment is configured with the tye.yml file
Run the environment with the tye run --watch command
To debug, attach your IDE to the spawned process

And that's it!

If you're hooked to Tye as I am, check out the Tye documentation for more information and different scenarios (with example configs).

Follow me on Twitter at @tim_deschryver | Subscribe to the Newsletter | Originally published on timdeschryver.dev.

DEV Community: Tim Deschryver

Announcing NgRx 21: Celebrating a 10 Year Journey with a fresh new look and @ngrx/signals/events

10 Year Anniversary 🎉

New Website 🎨

Welcome Rainer 🏆

The Events Plugin is stable 👏

The addition of Scoped Events

signalMethod and rxMethod accept a computation method

Updating to NgRx v21 🚀

A Big Thank You to Our Community! ❤️

Sponsor NgRx 🤝

What's Next?

Announcing NgRx 18: NgRx Signals is almost stable, ESLint v9 Support, New Logo and Redesign, Workshops, and more!

Stable NgRx Signals 🚦 (it's almost there)

ESLint Plugin support for ESLint v9 🧹

New NgRx Operators Package 🛠️

New Logo and Redesign of ngrx.io 💅

Deprecations and Breaking Changes 💥

Upgrading to NgRx 18 🗓️

NgRx Workshops 🎓

Swag Store and Discord Server 🦺

Contributing to NgRx 🥰

Thanks to all our contributors and sponsors! 🏆

Assertion Scopes, the one FluentAssertions feature you didn't know you needed

Conclusion

You should take advantage of the improved NgRx APIs

Actions

Reducers

Selectors

Registering the Store

Effects

Injecting the Store

Component Store

Watch out what you expose with Angular Interceptors

Conclusion

Keep your Playwright tests structured with steps

👎 Code comments

👎 Log statements

👍 Steps

Conclusion

New in Entity Framework 7: Bulk Operations with ExecuteDelete and ExecuteUpdate

Why

Setting the stage

ExecuteDelete and ExecuteDeleteAsync

Cascade delete

Number of rows affected

ExecuteUpdate and ExecuteUpdateAsync

Updating multiple values at once

Number of rows affected

More Updates in Entity Framework 7

How to upload files with Playwright

Get access to the deployed Azure Static Webb App URL within your GitHub Workflow

Exploring the new output caching middleware

Create a new API

Enable Output Caching

Add a caching layer to an endpoint

Cache by Query Parameter

Cache by Request Header

Cache by Value

Cache Expiration

Modify the default expiration time

Cache Purge

RouteGroups

Disable caching with NoCache

Policies

Named policies

Default (or "Base") policies

Cache locking

The DefaultPolicy implementation

Using OutputCache with Controllers

Conclusion

Feature Flags in .NET, from simple to more advanced

Setting the stage

Implementing a basic feature flag

Configurable feature flag

Introducing standards with the Feature Management package

Built-in filters

Writing a Custom Filter Implementation

Using Parameters within Custom Filters

FeatureGate for MVC Controllers

`signalMethod` and `rxMethod` accept a computation method

`ExecuteDelete` and `ExecuteDeleteAsync`

`ExecuteUpdate` and `ExecuteUpdateAsync`