Skip to content

Update the recommended way to reference feature flag name in README #275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 13, 2023
Merged

Update the recommended way to reference feature flag name in README #275

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fdd29a4
update the recommended way to reference feature flag name
zhiyuanliang-ms Oct 9, 2023
c3cc21a
remove nameof
zhiyuanliang-ms Oct 10, 2023
d2c79ea
remove recommended referencing way
zhiyuanliang-ms Oct 11, 2023
8905db3
using string literals directly
zhiyuanliang-ms Oct 12, 2023
68ea7f0
Merge branch 'main' into zhiyuanliang/readme-feature-name-referencing
zhiyuanliang-ms Oct 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 11 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,20 +138,6 @@ A `RequirementType` of `All` changes the traversal. First, if there are no filte
```

In the above example, `FeatureW` specifies a `RequirementType` of `All`, meaning all of it's filters must evaluate to true for the feature to be enabled. In this case, the feature will be enabled for 50% of users during the specified time window.

### Referencing

To make it easier to reference these feature flags in code, we recommend to define feature flag variables like below.

``` C#
// Define feature flags in an enum
public enum MyFeatureFlags
{
FeatureT,
FeatureU,
FeatureV
}
```

### Service Registration

Expand Down Expand Up @@ -187,7 +173,7 @@ The basic form of feature management is checking if a feature is enabled and the
…
IFeatureManager featureManager;
…
if (await featureManager.IsEnabledAsync(nameof(MyFeatureFlags.FeatureU)))
if (await featureManager.IsEnabledAsync("FeatureX"))
{
// Do something
}
Expand Down Expand Up @@ -216,7 +202,7 @@ The feature management library provides functionality in ASP.NET Core and MVC to
MVC controller and actions can require that a given feature, or one of any list of features, be enabled in order to execute. This can be done by using a `FeatureGateAttribute`, which can be found in the `Microsoft.FeatureManagement.Mvc` namespace.

``` C#
[FeatureGate(MyFeatureFlags.FeatureX)]
[FeatureGate("FeatureX")]
public class HomeController : Controller
{
…
Expand All @@ -226,14 +212,14 @@ public class HomeController : Controller
The `HomeController` above is gated by "FeatureX". "FeatureX" must be enabled before any action the `HomeController` contains can be executed.

``` C#
[FeatureGate(MyFeatureFlags.FeatureY)]
[FeatureGate("FeatureX")]
public IActionResult Index()
{
return View();
}
```

The `Index` MVC action above requires "FeatureY" to be enabled before it can execute.
The `Index` MVC action above requires "FeatureX" to be enabled before it can execute.

### Disabled Action Handling

Expand All @@ -251,7 +237,7 @@ public interface IDisabledFeaturesHandler
In MVC views `<feature>` tags can be used to conditionally render content based on whether a feature is enabled or not.

``` HTML+Razor
<feature name=@nameof(MyFeatureFlags.FeatureX)>
<feature name="FeatureX">
<p>This can only be seen if 'FeatureX' is enabled.</p>
</feature>
```
Expand All @@ -277,17 +263,17 @@ The feature management pipeline supports async MVC Action filters, which impleme
``` C#
services.AddMvc(o =>
{
o.Filters.AddForFeature<SomeMvcFilter>(nameof(MyFeatureFlags.FeatureV));
o.Filters.AddForFeature<SomeMvcFilter>("FeatureX");
});
```

The code above adds an MVC filter named `SomeMvcFilter`. This filter is only triggered within the MVC pipeline if the feature it specifies, "FeatureV", is enabled.
The code above adds an MVC filter named `SomeMvcFilter`. This filter is only triggered within the MVC pipeline if the feature it specifies, "FeatureX", is enabled.

### Razor Pages
MVC Razor pages can require that a given feature, or one of any list of features, be enabled in order to execute. This can be done by using a `FeatureGateAttribute`, which can be found in the `Microsoft.FeatureManagement.Mvc` namespace.

``` C#
[FeatureGate(MyFeatureFlags.FeatureU)]
[FeatureGate("FeatureX")]
public class IndexModel : PageModel
{
public void OnGet()
Expand All @@ -296,7 +282,7 @@ public class IndexModel : PageModel
}
```

The code above sets up a Razor page to require the "FeatureU" to be enabled. If the feature is not enabled, the page will generate an HTTP 404 (NotFound) result.
The code above sets up a Razor page to require the "FeatureX" to be enabled. If the feature is not enabled, the page will generate an HTTP 404 (NotFound) result.

When used on Razor pages, the `FeatureGateAttribute` must be placed on the page handler type. It cannot be placed on individual handler methods.

Expand All @@ -305,10 +291,10 @@ When used on Razor pages, the `FeatureGateAttribute` must be placed on the page
The feature management library can be used to add application branches and middleware that execute conditionally based on feature state.

``` C#
app.UseMiddlewareForFeature<ThirdPartyMiddleware>(nameof(MyFeatureFlags.FeatureU));
app.UseMiddlewareForFeature<ThirdPartyMiddleware>("FeatureX");
```

With the above call, the application adds a middleware component that only appears in the request pipeline if the feature "FeatureU" is enabled. If the feature is enabled/disabled during runtime, the middleware pipeline can be changed dynamically.
With the above call, the application adds a middleware component that only appears in the request pipeline if the feature "FeatureX" is enabled. If the feature is enabled/disabled during runtime, the middleware pipeline can be changed dynamically.

This builds off the more generic capability to branch the entire application based on a feature.

Expand Down