From 9eaa6829a7761299d8fa5d98d0d8a9787d6f2e5f Mon Sep 17 00:00:00 2001 From: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> Date: Fri, 10 Jan 2025 17:45:07 +0000 Subject: [PATCH 1/7] Add initial dotnet getting started tutorial * This includes mostly an introduction and basic installation documentation Signed-off-by: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> --- docs/tutorials/getting-started/dotnet.mdx | 62 +++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/tutorials/getting-started/dotnet.mdx diff --git a/docs/tutorials/getting-started/dotnet.mdx b/docs/tutorials/getting-started/dotnet.mdx new file mode 100644 index 00000000..373a9f43 --- /dev/null +++ b/docs/tutorials/getting-started/dotnet.mdx @@ -0,0 +1,62 @@ +--- +title: .NET SDK +description: Getting Started with the OpenFeature .NET SDK +--- + +import FlagdContent from '@site/src/components/custom/tutorial/flagd-content.mdx'; +import FlagdChangeContent from '@site/src/components/custom/tutorial/flagd-change-content.mdx'; +import WhyDefaultContent from '@site/src/components/custom/tutorial/why-default-content.mdx'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Getting Started with the OpenFeature .NET SDK + +## Introduction + +This walk-through teaches you the basics of using OpenFeature in .NET. + +You'll learn how to: + +- Integrate the OpenFeature .NET SDK +- Install and configure the OpenFeature provider +- Perform basic feature flagging + +## Requirements + +This walk-through assumes that: + +- You have a basic knowledge of C# and .NET +- You have installed the [.NET 8](https://dotnet.microsoft.com/en-us/) or later SDK + +## Walk-through + +### Step 1: Create a .NET 8 Console application + +To get started you can use the .NET SDK to initialise a console application. Open a terminal (**PowerShell**, **Command Prompt**, or **bash**) and paste the following commands: + +```powershell +dotnet new console -o openfeature-dotnet-sample +cd openfeature-dotnet-sample +dotnet run +``` + +### Step 2: Add dependencies + +With NuGet you can install the latest [OpenFeature](https://www.nuget.org/packages/OpenFeature) package into your .NET console application. + +```powershell +dotnet add package OpenFeature +``` + +### Step 3: Add code + +### Step 5: Configure a provider (flagd) + +### Step 4: Run the initial application + +## Conclusion + +This walk-through introduced you to the OpenFeature .NET SDK. +It covered how a provider can be configured to perform the flag evaluation and introduced basic feature +flagging concepts. +It also showcased how feature flags can be updated at runtime, without requiring a code change and a redeployment. From 9e784bdd1834c2e6a14a3e159c038a8415b4455e Mon Sep 17 00:00:00 2001 From: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> Date: Fri, 10 Jan 2025 22:44:52 +0000 Subject: [PATCH 2/7] Add .NET Getting Started tutorial documentation Signed-off-by: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> --- docs/tutorials/getting-started/dotnet.mdx | 200 ++++++++++++++++++++-- 1 file changed, 188 insertions(+), 12 deletions(-) diff --git a/docs/tutorials/getting-started/dotnet.mdx b/docs/tutorials/getting-started/dotnet.mdx index 373a9f43..7ca4a1ea 100644 --- a/docs/tutorials/getting-started/dotnet.mdx +++ b/docs/tutorials/getting-started/dotnet.mdx @@ -1,19 +1,16 @@ --- -title: .NET SDK +title: .NET SDK and ASP.NET Core description: Getting Started with the OpenFeature .NET SDK --- import FlagdContent from '@site/src/components/custom/tutorial/flagd-content.mdx'; import FlagdChangeContent from '@site/src/components/custom/tutorial/flagd-change-content.mdx'; -import WhyDefaultContent from '@site/src/components/custom/tutorial/why-default-content.mdx'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; # Getting Started with the OpenFeature .NET SDK ## Introduction -This walk-through teaches you the basics of using OpenFeature in .NET. +This walk-through teaches you the basics of using OpenFeature in .NET within a ASP.NET Core Web application. You'll learn how to: @@ -30,30 +27,209 @@ This walk-through assumes that: ## Walk-through -### Step 1: Create a .NET 8 Console application +### Step 1: Create a .NET 8 Web application -To get started you can use the .NET SDK to initialise a console application. Open a terminal (**PowerShell**, **Command Prompt**, or **bash**) and paste the following commands: +To get started you can use the .NET SDK to initialise a web application. Open a terminal (**shell**, **Command Prompt**, or **bash**) and paste the following commands: -```powershell -dotnet new console -o openfeature-dotnet-sample +```shell +dotnet new webapi -o openfeature-dotnet-sample cd openfeature-dotnet-sample dotnet run ``` ### Step 2: Add dependencies -With NuGet you can install the latest [OpenFeature](https://www.nuget.org/packages/OpenFeature) package into your .NET console application. +With NuGet you can install the latest [OpenFeature](https://www.nuget.org/packages/OpenFeature) package into your .NET web application. -```powershell +```shell dotnet add package OpenFeature ``` ### Step 3: Add code -### Step 5: Configure a provider (flagd) +The following will initialise an `InMemoryProvider` for use within the web application. Open a code editor and add the C# code below to the Program.cs. + +```csharp +// diff-add-block-start +using OpenFeature; +using OpenFeature.Providers.Memory; +// diff-add-block-end + +var builder = WebApplication.CreateBuilder(args); + +// Add services to the container. +// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi +builder.Services.AddOpenApi(); + +var app = builder.Build(); + +// diff-add-block-start +// Register your feature flag provider +await Api.Instance.SetProviderAsync(new InMemoryProvider()); +// diff-add-block-end + +// Configure the HTTP request pipeline. +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} + +app.UseHttpsRedirection(); + +//diff-remove-block-start +var summaries = new[] +{ + "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" +}; +//diff-remove-block-end + +//diff-remove-block-start +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; +}) +.WithName("GetWeatherForecast"); +//diff-remove-block-end +//diff-add-block-start +app.MapGet("/hello", async () => +{ + var client = Api.Instance.GetClient(); + + if (await client.GetBooleanValueAsync("welcome-message", false)) + { + return "Hello, welcome to this OpenFeature-enabled website!"; + } + + return "Hello"; +}) +.WithName("GetHello"); +//diff-add-block-end + +app.Run(); + +//diff-remove-block-start +record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) +{ + public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); +} +//diff-remove-block-end +``` + +At this point, we are ready to run the initial version of our application. ### Step 4: Run the initial application +Let's compile and run the application. + +```shell +dotnet build +dotnet run +``` + +In the logs you should see a line with the following `Now listening on: http://localhost:5251`, although the port number may differ. You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should the message "Hello". + +At the moment, our application is configured with an InMemoryProvider. No flags have been passed to the provider, so by default the value specified in `GetBooleanValueAsync` method will return false. + +We can configure the InMemoryProvider and pass some configuration. + +```csharp +// diff-add-block-start +var features = new Dictionary() +{ + { "welcome-message", new Flag(new Dictionary { { "on", true } }, "on") } +}; +// diff-add-block-end + +// diff-remove +await Api.Instance.SetProviderAsync(new InMemoryProvider()); +// diff-add +await Api.Instance.SetProviderAsync(new InMemoryProvider(flags)); +``` + +If you run the application again, and repeat the request to `/hello`, you will see the phrase "Hello, welcome to this OpenFeature-enabled website!" + +### Step 5: Configure a provider (flagd) + + + +Finally, let's add the required code change to enable the flagd provider in our .NET application. First we need to install the [.NET OpenFeature Flagd](https://www.nuget.org/packages/OpenFeature.Contrib.Providers.Flagd/) package. + +```shell +dotnet add package OpenFeature.Contrib.Providers.Flagd +``` + +Next, we need to make small change to the `SetProviderAsync` method and pass in the `FlagdProvider`. + +```csharp + +using OpenFeature; +//diff-add +using OpenFeature.Contrib.Providers.Flagd +using OpenFeature.Providers.Memory; + +var builder = WebApplication.CreateBuilder(args); + +// Add services to the container. +// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi +builder.Services.AddOpenApi(); + +var app = builder.Build(); + +// Register your feature flag provider +//diff-remove +await Api.Instance.SetProviderAsync(new InMemoryProvider()); +//diff-add-block-start +var flagdProvider = new FlagdProvider(new Uri("http://localhost:8013")); +await Api.Instance.SetProviderAsync(flagdProvider); +//diff-add-block-end + +// Configure the HTTP request pipeline. +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} + +app.UseHttpsRedirection(); + +app.MapGet("/hello", async () => +{ + var client = Api.Instance.GetClient(); + + if (await client.GetBooleanValueAsync("welcome-message", false)) + { + return "Hello, welcome to this OpenFeature-enabled website!"; + } + + return "Hello"; +}) +.WithName("GetHello"); + +app.Run(); +``` + +### Step 6: Rerun the application + +We can use the .NET CLI to build and run our application. + +```shell +dotnet build +dotnet run +``` + +You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should the message "Hello". + + + +Revisit the endpoint http://localhost:5251/hello and you will be greeted with `Hello, welcome to this OpenFeature-enabled website!` + ## Conclusion This walk-through introduced you to the OpenFeature .NET SDK. From 12dd1ea5359317f7ca30638414213df9735befc2 Mon Sep 17 00:00:00 2001 From: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> Date: Fri, 10 Jan 2025 22:51:02 +0000 Subject: [PATCH 3/7] Add docker requirement for flagd Signed-off-by: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> --- docs/tutorials/getting-started/dotnet.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tutorials/getting-started/dotnet.mdx b/docs/tutorials/getting-started/dotnet.mdx index 7ca4a1ea..3fd9eac8 100644 --- a/docs/tutorials/getting-started/dotnet.mdx +++ b/docs/tutorials/getting-started/dotnet.mdx @@ -24,6 +24,7 @@ This walk-through assumes that: - You have a basic knowledge of C# and .NET - You have installed the [.NET 8](https://dotnet.microsoft.com/en-us/) or later SDK +- You have Docker installed and running on the host system ## Walk-through From 5067c378764e0d4f1ddf61ba4ab6ba0ca04e27d0 Mon Sep 17 00:00:00 2001 From: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> Date: Fri, 10 Jan 2025 23:01:03 +0000 Subject: [PATCH 4/7] Tweak documentation to be more consistent * Tweaking to align with the other tutorials Signed-off-by: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> --- docs/tutorials/getting-started/dotnet.mdx | 32 +++++------------------ 1 file changed, 7 insertions(+), 25 deletions(-) diff --git a/docs/tutorials/getting-started/dotnet.mdx b/docs/tutorials/getting-started/dotnet.mdx index 3fd9eac8..6105a09a 100644 --- a/docs/tutorials/getting-started/dotnet.mdx +++ b/docs/tutorials/getting-started/dotnet.mdx @@ -109,7 +109,7 @@ app.MapGet("/hello", async () => return "Hello, welcome to this OpenFeature-enabled website!"; } - return "Hello"; + return "Hello!"; }) .WithName("GetHello"); //diff-add-block-end @@ -135,39 +135,21 @@ dotnet build dotnet run ``` -In the logs you should see a line with the following `Now listening on: http://localhost:5251`, although the port number may differ. You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should the message "Hello". +In the logs you should see a line with the following `Now listening on: http://localhost:5251`, although the port number may differ. You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should the message "Hello!". -At the moment, our application is configured with an InMemoryProvider. No flags have been passed to the provider, so by default the value specified in `GetBooleanValueAsync` method will return false. - -We can configure the InMemoryProvider and pass some configuration. - -```csharp -// diff-add-block-start -var features = new Dictionary() -{ - { "welcome-message", new Flag(new Dictionary { { "on", true } }, "on") } -}; -// diff-add-block-end - -// diff-remove -await Api.Instance.SetProviderAsync(new InMemoryProvider()); -// diff-add -await Api.Instance.SetProviderAsync(new InMemoryProvider(flags)); -``` - -If you run the application again, and repeat the request to `/hello`, you will see the phrase "Hello, welcome to this OpenFeature-enabled website!" +"Why I'm I seeing that value?", you may ask. Well, it's because a provider hasn't been configured yet. Without a provider to actually evaluate flags, OpenFeature will return the default value. In the next step, you'll learn how to add a provider. ### Step 5: Configure a provider (flagd) -Finally, let's add the required code change to enable the flagd provider in our .NET application. First we need to install the [.NET OpenFeature Flagd](https://www.nuget.org/packages/OpenFeature.Contrib.Providers.Flagd/) package. +Before we can use the Flagd provider in .NET we need to install the [.NET OpenFeature Flagd](https://www.nuget.org/packages/OpenFeature.Contrib.Providers.Flagd/) package. ```shell dotnet add package OpenFeature.Contrib.Providers.Flagd ``` -Next, we need to make small change to the `SetProviderAsync` method and pass in the `FlagdProvider`. +Finally, let's add the required code change to enable the flagd provider in our .NET application. ```csharp @@ -209,7 +191,7 @@ app.MapGet("/hello", async () => return "Hello, welcome to this OpenFeature-enabled website!"; } - return "Hello"; + return "Hello!"; }) .WithName("GetHello"); @@ -225,7 +207,7 @@ dotnet build dotnet run ``` -You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should the message "Hello". +You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should the message "Hello!". From 367f95cf59fa2af26bc295009e6cccc9c9047991 Mon Sep 17 00:00:00 2001 From: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> Date: Fri, 10 Jan 2025 23:13:09 +0000 Subject: [PATCH 5/7] Fix issue with seeing the hello world message Signed-off-by: Kyle Julian <38759683+kylejuliandev@users.noreply.github.com> --- docs/tutorials/getting-started/dotnet.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/getting-started/dotnet.mdx b/docs/tutorials/getting-started/dotnet.mdx index 6105a09a..148b365e 100644 --- a/docs/tutorials/getting-started/dotnet.mdx +++ b/docs/tutorials/getting-started/dotnet.mdx @@ -135,7 +135,7 @@ dotnet build dotnet run ``` -In the logs you should see a line with the following `Now listening on: http://localhost:5251`, although the port number may differ. You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should the message "Hello!". +In the logs you should see a line with the following `Now listening on: http://localhost:5251`, although the port number may differ. You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should see the message "Hello!". "Why I'm I seeing that value?", you may ask. Well, it's because a provider hasn't been configured yet. Without a provider to actually evaluate flags, OpenFeature will return the default value. In the next step, you'll learn how to add a provider. @@ -207,7 +207,7 @@ dotnet build dotnet run ``` -You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should the message "Hello!". +You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should see the message "Hello!". From e05cbd0a2bc9e4bf1bb6319d06ccd726d7aa8aff Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Wed, 15 Jan 2025 11:46:26 -0500 Subject: [PATCH 6/7] Apply suggestions from code review Signed-off-by: Michael Beemer --- docs/tutorials/getting-started/dotnet.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/getting-started/dotnet.mdx b/docs/tutorials/getting-started/dotnet.mdx index 148b365e..bd478678 100644 --- a/docs/tutorials/getting-started/dotnet.mdx +++ b/docs/tutorials/getting-started/dotnet.mdx @@ -135,7 +135,7 @@ dotnet build dotnet run ``` -In the logs you should see a line with the following `Now listening on: http://localhost:5251`, although the port number may differ. You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should see the message "Hello!". +In the logs you should see a line with the following `Now listening on: http://localhost:5251`, although the port number may differ. You can visit the following URL in your browser [http://localhost:5251/hello](http://localhost:5251/hello) (adjust port number as necessary) to view the hello world message. You should see the message "Hello!". "Why I'm I seeing that value?", you may ask. Well, it's because a provider hasn't been configured yet. Without a provider to actually evaluate flags, OpenFeature will return the default value. In the next step, you'll learn how to add a provider. @@ -156,6 +156,7 @@ Finally, let's add the required code change to enable the flagd provider in our using OpenFeature; //diff-add using OpenFeature.Contrib.Providers.Flagd +//diff-remove using OpenFeature.Providers.Memory; var builder = WebApplication.CreateBuilder(args); From d4abf0c282014bc734d91a2343d3757e41fc6cfd Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Wed, 15 Jan 2025 11:55:08 -0500 Subject: [PATCH 7/7] Address linting issues Signed-off-by: Michael Beemer --- docs/tutorials/getting-started/dotnet.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/getting-started/dotnet.mdx b/docs/tutorials/getting-started/dotnet.mdx index bd478678..a114e489 100644 --- a/docs/tutorials/getting-started/dotnet.mdx +++ b/docs/tutorials/getting-started/dotnet.mdx @@ -208,11 +208,11 @@ dotnet build dotnet run ``` -You can visit the following URL in your browser http://localhost:5251/hello (adjust port number as necessary) to view the hello world message. You should see the message "Hello!". +You can visit the following URL in your browser [http://localhost:5251/hello](http://localhost:5251/hello) (adjust port number as necessary) to view the hello world message. You should see the message "Hello!". -Revisit the endpoint http://localhost:5251/hello and you will be greeted with `Hello, welcome to this OpenFeature-enabled website!` +Revisit the endpoint [http://localhost:5251/hello](http://localhost:5251/hello) and you will be greeted with `Hello, welcome to this OpenFeature-enabled website!` ## Conclusion