Merge pull request #26 from microsoft/dev

Update master for release.

Author: jimmyca15

.pipelines/pipeline.user.windows.yml

@@ -10,7 +10,7 @@ restore:
     - !!defaultcommand
       name: 'Restore'
       command: 'build.cmd'
-      arguments: 'RestoreOnly'
+      arguments: '-RestoreOnly'
 
 build:
   commands:

Microsoft.FeatureManagement.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio 15
-VisualStudioVersion = 15.0.28119.50
+# Visual Studio Version 16
+VisualStudioVersion = 16.0.29011.400
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "FeatureFlagDemo", "examples\FeatureFlagDemo\FeatureFlagDemo.csproj", "{E58A64A6-BE10-4D7A-AAB8-C3E2925CB32F}"
 EndProject
@@ -13,6 +13,10 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tests", "Tests", "{8ED6FFEE
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.FeatureManagement.AspNetCore", "src\Microsoft.FeatureManagement.AspNetCore\Microsoft.FeatureManagement.AspNetCore.csproj", "{CFD3E549-2E24-490D-A7F6-F95E56A81092}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Examples", "Examples", "{FB5C34DF-695C-4DF9-8AED-B3EA2516EA72}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ConsoleApp", "examples\ConsoleApp\ConsoleApp.csproj", "{E50FB931-7A42-440E-AC47-B8DFE5E15394}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -35,12 +39,18 @@ Global
 		{CFD3E549-2E24-490D-A7F6-F95E56A81092}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{CFD3E549-2E24-490D-A7F6-F95E56A81092}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{CFD3E549-2E24-490D-A7F6-F95E56A81092}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E50FB931-7A42-440E-AC47-B8DFE5E15394}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E50FB931-7A42-440E-AC47-B8DFE5E15394}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E50FB931-7A42-440E-AC47-B8DFE5E15394}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E50FB931-7A42-440E-AC47-B8DFE5E15394}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
+		{E58A64A6-BE10-4D7A-AAB8-C3E2925CB32F} = {FB5C34DF-695C-4DF9-8AED-B3EA2516EA72}
 		{FDBB27BA-C5BA-48A7-BA9B-63159943EA9F} = {8ED6FFEE-4037-49A2-9709-BC519C104A90}
+		{E50FB931-7A42-440E-AC47-B8DFE5E15394} = {FB5C34DF-695C-4DF9-8AED-B3EA2516EA72}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {84DA6C54-F140-4518-A1B4-E4CF42117FBD}

README.md

@@ -10,6 +10,9 @@ Here are some of the benefits of using this library:
   * Supports JSON file feature flag setup
 * Feature Flag lifetime management
   * Configuration values can change in real-time, feature flags can be consistent across the entire request
+* Simple to Complex Scenarios Covered
+  * Toggle on/off features through declarative configuration file
+  * Dynamically evaluate state of feature based on call to server
 * API extensions for ASP.Net Core and MVC framework
   * Routing
   * Filters
@@ -128,13 +131,13 @@ This tells the feature manager to use the "FeatureManagement" section from the c
 The simplest use case for feature flags is to do a conditional check for whether a feature is enabled to take different paths in code. The uses cases grow from there as the feature flag API begins to offer extensions into ASP.Net Core.
 
 ### Feature Check
-The basic form of feature management is checking if a feature is enabled and then performing actions based on the result. This is done through the `IFeatureManager`'s `IsEnabled` method.
+The basic form of feature management is checking if a feature is enabled and then performing actions based on the result. This is done through the `IFeatureManager`'s `IsEnabledAsync` method.
 
 ```
 ...
 IFeatureManager featureManager;
 ...
-if (featureManager.IsEnabled(nameof(MyFeatureFlags.FeatureU)))
+if (await featureManager.IsEnabledAsync(nameof(MyFeatureFlags.FeatureU)))
 {
     // Do something
 }
@@ -207,7 +210,8 @@ The `<feature>` tag requires a tag helper to work. This can be done by adding th
 
 ### MVC Filters
 
-MVC filters can be set up to conditionally execute based on the state of a feature. This is done by registering MVC filters in a feature aware manner.
+MVC action filters can be set up to conditionally execute based on the state of a feature. This is done by registering MVC filters in a feature aware manner.
+The feature management pipeline supports async MVC Action filters, which implement `IAsyncActionFilter`.
 
 ```
 services.AddMvc(o => 
@@ -218,18 +222,6 @@ services.AddMvc(o =>
 
 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.
 
-### Routing
-Certain routes may expose application capabilites that are gated by features. These routes can be dynamically registered and exposed based on whether a feature is enabled.
-
-```
-app.UseMvc(routes =>
-{
-    routes.MapRouteForFeature(nameof(MyFeatureFlags.Beta), "betaDefault" /* route name */, "{controller=Beta}/{action=Index}/{id?}"
-});
-```
-
-The route above exposes beta functionality of some application that is gated behind the "Beta" feature flag. The state of this feature is evaluated on every request, which means routes can be exposed to a subset of requests and or users. Furthermore, routes can dynamically be added or removed based on the toggling of feature states.
-
 ### Application building
 
 The feature management library can be used to add application branches and middleware that execute conditionally based on feature state.
@@ -251,13 +243,13 @@ app.UseForFeature(featureName, appBuilder =>
 
 ## Implementing a Feature Filter
 
-Creating a feature filter provides a way to enable features based on criteria that you define. To implement a feature filter, the `IFeatureFilter` interface must be implemented. `IFeatureFilter` has a single method named `Evaluate`. When a feature specifies that it can be enabled for a feature filter, the `Evaluate` method is called. If `Evaluate` returns `true` it means the feature should be enabled.
+Creating a feature filter provides a way to enable features based on criteria that you define. To implement a feature filter, the `IFeatureFilter` interface must be implemented. `IFeatureFilter` has a single method named `EvaluateAsync`. When a feature specifies that it can be enabled for a feature filter, the `EvaluateAsync` method is called. If `EvaluateAsync` returns `true` it means the feature should be enabled.
 
 Feature filters are registered by the `IFeatureManagementBuilder` when `AddFeatureManagement` is called. These feature filters have access to the services that exist within the service collection that was used to add feature flags. Dependency injection can be used to retrieve these services.
 
 ### Parameterized Feature Filters
 
-Some feature filters require parameters to decide whether a feature should be turned on or not. For example a browser feature filter may turn on a feature for a certain set of browsers. It may be desired that Edge and Chrome browsers enable a feature, while FireFox does not. To do this a feature filter can be designed to expect parameters. These parameters would be specified in the feature configuration, and in code would be accessible via the `FeatureFilterEvaluationContext` parameter of `IFeatureFilter.Evaluate`.
+Some feature filters require parameters to decide whether a feature should be turned on or not. For example a browser feature filter may turn on a feature for a certain set of browsers. It may be desired that Edge and Chrome browsers enable a feature, while FireFox does not. To do this a feature filter can be designed to expect parameters. These parameters would be specified in the feature configuration, and in code would be accessible via the `FeatureFilterEvaluationContext` parameter of `IFeatureFilter.EvaluateAsync`.
 
 ```
   public class FeatureFilterEvaluationContext
@@ -282,7 +274,7 @@ Some feature filters require parameters to decide whether a feature should be tu
   {
       ... Removed for example
 
-      public bool Evaluate(FeatureFilterEvaluationContext context)
+      public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
       {
           BrowserFilterSettings settings = context.Parameters.Get<BrowserFilterSettings>() ?? new BrowserFilterSettings();
 
@@ -333,6 +325,46 @@ public void ConfigureServices(IServiceCollection services)
 }
 ```
 
+## Providing a Context For Feature Evaluation
+
+In console applications there is no ambient context such as `HttpContext` that feature filters can acquire and utilize to check if a feature should be on or off. In this case, applications need to provide an object representing a context into the feature management system for use by feature filters. This is done by using `IFeatureManager.IsEnabledAsync<TContext>(string featureName, TContext appContext)`. The appContext object that is provided to the feature manager can be used by feature filters to evaluate the state of a feature.
+
+```
+  MyAppContext context = new MyAppContext
+  {
+    AccountId = current.Id;
+  }
+
+  if (featureManager.IsEnabled(feature, context))
+  {
+  }
+```
+
+### Contextual Feature Filters
+
+Contextual feature filters implement the `IContextualFeatureFilter<TContext>` interface. These special feature filters can take advantage of the context that is passed in when `IFeatureManager.IsEnabledAsync<TContext>` is called. The `TContext` type parameter in `IContextualFeatureFilter<TContext>` describes what context type the filter is capable of handling. This allows the developer of a contextual feature filter to describe what is required of those who wish to utilize it. Since every type is a descendant of object, a filter that implements `IContextualFeatureFilter<object>` can be called for any provided context. To illustrate an example of a more specific contextual feature filter, consider a feature that is enabled if an account is in a configured list of enabled accounts. 
+
+```    
+  public interface IAccountContext
+  {
+    string AccountId { get; set; }
+  }
+
+  [FilterAlias("AccountId")]
+  class AccountIdFilter : IContextualFeatureFilter<IAccountContext>
+  {
+    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext featureEvaluationContext, IAccountContext accountId)
+    {
+      //
+      // Evaluate if the feature should be on with the help of the provided IAccountContext
+    }
+  }
+```
+
+We can see that the `AccountIdFilter` requires an object that implements `IAccountContext` to be provided to be able to evalute the state of a feature. When using this feature filter, the caller needs to make sure that the passed in object implements `IAccountContext`.
+
+**Note:** Only a single feature filter interface can be implemented by a single type. Trying to add a feature filter that implements more than a single feature filter interface will result in an `ArgumentException`.
+
 ### Built-In Feature Filters
 
 There a few feature filters that come with the `Microsoft.FeatureManagement` package. These feature filters are not added automatically, but can be referenced and registered as soon as the package is registered.
@@ -360,7 +392,8 @@ This filter provides the capability to enable a feature based on a set percentag
 
 This filter provides the capability to enable a feature based on a time window. If only `End` is specified, the feature will be considered on until that time. If only start is specified, the feature will be considered on at all points after that time.
 
-```    "EnhancedPipeline": {
+```
+    "EnhancedPipeline": {
       "EnabledFor": [
         {
           "Name": "Microsoft.TimeWindow",

build.cmd

@@ -1 +1,3 @@
-powershell.exe -ExecutionPolicy Unrestricted -NoProfile -File "%~dp0build.ps1"
+call %~dp0build\InstallPowerShellCore.cmd
+
+%PowerShellCore% "%~dp0build.ps1" %*

build.ps1

@@ -10,7 +10,10 @@ Indicates whether the build config should be set to Debug or Release. The defaul
 param(
     [Parameter()]
     [ValidateSet('Debug','Release')]
-    [string]$BuildConfig = "Release"
+    [string]$BuildConfig = "Release",
+    
+    [Parameter()]
+    [switch]$RestoreOnly = $false
 )
 
 $ErrorActionPreference = "Stop"
@@ -24,7 +27,15 @@ if ((Test-Path -Path $LogDirectory) -ne $true) {
     New-Item -ItemType Directory -Path $LogDirectory | Write-Verbose
 }
 
-# Build
-dotnet build -o "$BuildRelativePath" -c $BuildConfig "$Solution" | Tee-Object -FilePath "$LogDirectory\build.log"
+if ($RestoreOnly)
+{
+    # Restore
+    dotnet restore "$Solution"
+}
+else
+{
+    # Build
+    dotnet build -o "$BuildRelativePath" -c $BuildConfig "$Solution" | Tee-Object -FilePath "$LogDirectory\build.log"
+}
 
 exit $LASTEXITCODE

build/InstallPowerShellCore.cmd

@@ -0,0 +1,5 @@
+if not exist "%USERPROFILE%\.dotnet\tools\pwsh.exe" (
+  dotnet tool install --global PowerShell --version 6.2.3
+)
+
+set PowerShellCore="%USERPROFILE%\.dotnet\tools\pwsh.exe"

build/NugetProperties.props

@@ -19,7 +19,7 @@
     <MinutesSinceMidnight>$([MSBuild]::Divide($(TicksSinceMidnight), 600000000))</MinutesSinceMidnight>
     <Floored>$([System.Math]::Floor($(MinutesSinceMidnight)))</Floored>
     <Revision>$(Floored)</Revision>
-    <Version>1.0.0-preview-$(CDP_PATCH_NUMBER)-$(Revision)</Version>
+    <Version>2.0.0-preview-$(CDP_PATCH_NUMBER)-$(Revision)</Version>
   </PropertyGroup>
 
 </Project>

examples/ConsoleApp/AccountServiceContext.cs

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+using Consoto.Banking.AccountService.FeatureFilters;
+
+namespace Consoto.Banking.AccountService
+{
+    class AccountServiceContext : IAccountContext
+    {
+        public string AccountId { get; set; }
+    }
+}

examples/ConsoleApp/ConsoleApp.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp2.1</TargetFramework>
+    <RootNamespace>Consoto.Banking.AccountService</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="2.1.1" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="2.1.1" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Microsoft.FeatureManagement\Microsoft.FeatureManagement.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Update="appsettings.json">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

examples/ConsoleApp/FeatureFilters/AccountIdFilter.cs

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+using Consoto.Banking.AccountService.FeatureFilters;
+using Microsoft.Extensions.Configuration;
+using Microsoft.FeatureManagement;
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+namespace Consoto.Banking.AccountService.FeatureManagement
+{
+    /// <summary>
+    /// A filter that uses the feature management context to ensure that the current task has the notion of an account id, and that the account id is allowed.
+    /// This filter will only be executed if an object implementing <see cref="IAccountContext"/> is passed in during feature evaluation.
+    /// </summary>
+    [FilterAlias("AccountId")]
+    class AccountIdFilter : IContextualFeatureFilter<IAccountContext>
+    {
+        public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext featureEvaluationContext, IAccountContext accountContext)
+        {
+            if (string.IsNullOrEmpty(accountContext?.AccountId))
+            {
+                throw new ArgumentNullException(nameof(accountContext));
+            }
+
+            var allowedAccounts = new List<string>();
+
+            featureEvaluationContext.Parameters.Bind("AllowedAccounts", allowedAccounts);
+
+            return Task.FromResult(allowedAccounts.Contains(accountContext.AccountId));
+        }
+    }
+}

examples/ConsoleApp/FeatureFilters/IAccountContext.cs

@@ -0,0 +1,10 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+namespace Consoto.Banking.AccountService.FeatureFilters
+{
+    public interface IAccountContext
+    {
+        string AccountId { get; }
+    }
+}

examples/ConsoleApp/Program.cs

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+using Consoto.Banking.AccountService.FeatureManagement;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.FeatureManagement;
+using Microsoft.FeatureManagement.FeatureFilters;
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+namespace Consoto.Banking.AccountService
+{
+    class Program
+    {
+        public static async Task Main(string[] args)
+        {
+            //
+            // Setup configuration
+            IConfiguration configuration = new ConfigurationBuilder()
+                .AddJsonFile("appsettings.json")
+                .Build();
+
+            //
+            // Setup application services + feature management
+            IServiceCollection services = new ServiceCollection();
+
+            services.AddSingleton(configuration)
+                    .AddFeatureManagement()
+                    .AddFeatureFilter<PercentageFilter>()
+                    .AddFeatureFilter<AccountIdFilter>();
+
+            //
+            // Get the feature manager from application services
+            using (ServiceProvider serviceProvider = services.BuildServiceProvider())
+            {
+                IFeatureManager featureManager = serviceProvider.GetRequiredService<IFeatureManager>();
+
+                var accounts = new List<string>()
+                {
+                    "abc",
+                    "adef",
+                    "abcdefghijklmnopqrstuvwxyz"
+                };
+
+                //
+                // Mimic work items in a task-driven console application
+                foreach (var account in accounts)
+                {
+                    const string FeatureName = "Beta";
+
+                    //
+                    // Check if feature enabled
+                    //
+                    var accountServiceContext = new AccountServiceContext
+                    {
+                        AccountId = account
+                    };
+
+                    bool enabled = await featureManager.IsEnabledAsync(FeatureName, accountServiceContext);
+
+                    //
+                    // Output results
+                    Console.WriteLine($"The {FeatureName} feature is {(enabled ? "enabled" : "disabled")} for the '{account}' account.");
+                }
+            }
+        }
+    }
+}