Managed identities are a great feature and very easy to use for built-in workloads like VMs, Azure Container Apps, App Services. However, until recently, managed identities could not be used for non-native workloads like GitHub Actions. We had to use an Azure AD app registration instead and store its credentials (including a CLIENT_SECRET) as GitHub secrets. With the introduction of workload identity federation for app registrations, it was then possible to configure a trust relationship between GitHub and Azure that allows the GitHub Actions to authenticate to Azure without the need for providing a CLIENT_SECRET. This would have already solved my requirement for not needing any secrets, but the problem is, that creating an Azure AD app registration requires elevated permissions and therefore often can’t easily be done by regular developers.

The good news is that Microsoft now also supports federated credentials for user-assigned managed identities! Managed identities only require regular Azure RBAC rights and can be created via Bicep templates and are therefore much easier to integrate into Infrastructure as Code-processes and CI/CD systems.

Uday Hegde has written a good blog post explaining federated credentials for managed identities: https://blog.identitydigest.com/azuread-federate-mi/

The remainder of this blog post will focus on how federated credentials for managed identities are used in my microservices template. Have a look at the project’s README.md for more details.

Overview

For my microservices template, the entire process for creating the Azure resources and connecting GitHub with Azure is automated via the init-platform.ps1 script. The script must be executed manually once, since there’s the “chicken and egg”-problem of already needing the managed identity to deploy Azure resources via a GitHub workflow.

The script will execute the following steps (among other things that are out of scope for this post):

• It will create a resource group in Azure that will host the managed identity.
• It will create a user-assigned managed identity in this resource group.
• The managed identity will be given Contributor & UserAccessAdministrator rights on the Azure subscription.
  • (So that the GitHub workflows of my services can create Azure resources and assign rights to newly created managed identities)
• The managed identity will be given additional AAD permissions.
  • (My GitHub workflows need to be able to query AAD groups)
• A GitHub environment called platform will be created via the GitHub CLI.
  • This will be used to protect further deployments with required reviewers or other protection rules.
• Federated credentials will be added to the managed identity for the main-branch and for the platform-environment.
  • There must be a federated credential for each branch and GitHub environment that we want to deploy from.
• The necessary resource IDs (tenant id, subscription id, client id of our managed identity) will be created as GitHub secrets

Deploying the managed identity and its federated credentials to Azure

The template creates all Azure resources via Bicep-templates stored in the infrastructure directory. The managed identity for GitHub is part of the platform-resources that are shared by all environments of my microservice template (e.g., development, production).

To create the managed identity for GitHub, the following Bicep-template is used:

resource githubIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2022-01-31-preview' = {
  name: githubIdentityName
  location: location
  tags: tags
}

(Original source)

Creating the federated credentials via Bicep is more complex. Since I need federated credentials for the main-branch, the shared platform-environment, and each actual application environment (development, production), I’m creating a list variable that holds the name and subject for each credential based on my global config-file:

var config = loadJsonContent('./../config.json')

// All credentials must be in one list as concurrent writes to /federatedIdentityCredentials are not allowed.
var ghBranchCredentials = [{
  name: 'github-branch-${githubDefaultBranchName}'
  subject: 'repo:${githubRepoNameWithOwner}:ref:refs/heads/${githubDefaultBranchName}'
}]
var ghPlatformCredentials = [{
  name: 'github-env-platform'
  subject: 'repo:${githubRepoNameWithOwner}:environment:platform'
}]
var ghEnvironmentCredentials = [for item in items(config.environments): {
  name: 'github-env-${item.key}'
  subject: 'repo:${githubRepoNameWithOwner}:environment:${item.key}'
}]
var githubCredentials = concat(ghBranchCredentials, ghPlatformCredentials, ghEnvironmentCredentials)

(Original source)

The credential resources are then created via a Bicep-loop. It’s important that batchSize(1) is used because concurrent writes are not supported and will result in a deployment error.

@batchSize(1)
resource federatedCredentials 'Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials@2022-01-31-preview' = [for item in githubCredentials: {
  name: item.name
  parent: githubIdentity
  properties: {
    audiences: [
      'api://AzureADTokenExchange'
    ]
    issuer: 'https://token.actions.githubusercontent.com'
    subject: item.subject
  }
}]

(Original source)

The fields audiences, issuer and subject are set according to the requirements by GitHub.

Assigning RBAC-roles to the managed identity

In order for my GitHub-worflows to be able to deploy resources to Azure, the managed identity must have the appropriate RBAC permissions. For my template, I’m assigning the Contributor-role and UserAccessAdministrator-role at the subscription-scope to the identity. The UserAccessAdministrator-role is necessary to allow my GitHub workflows to create other managed identities and to assign RBAC-roles to them.

To assign a RBAC-role, we must know its internal ID. For built-in roles, this ID can be found here: https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles

Here’s the code to reference the Contributor-role:

resource contributorRoleDefinition 'Microsoft.Authorization/roleDefinitions@2022-04-01' existing = {
  scope: subscription()
  name: 'b24988ac-6180-42a0-ab88-20f7382dd24c'
}

(Original source)

With the reference to the role definition, we can now create the actual role assignment for the managed identity:

resource githubIdentityContributor 'Microsoft.Authorization/roleAssignments@2020-04-01-preview' = {
  name: guid(subscription().id, 'github', 'Contributor')
  properties: {
    roleDefinitionId: contributorRoleDefinition.id
    principalId: githubIdentity.outputs.githubIdentityPrincipalId
    principalType: 'ServicePrincipal'
  }
}

(Original source)

NOTE: Azure does not automatically delete RBAC-role assignments when the managed identity is deleted. You must manually delete them or future re-deployments will fail with a conflict.

Assigning AAD permissions to the managed identity

Some of my GitHub workflows need to be able to query the Azure AD graph for details about an Azure AD group and to do so, the managed identity must have the proper AAD permissions.

Unfortunately, AAD resources and permissions can NOT be created via Bicep templates, so we need to either use the AzureAD-module (which is planned for deprecation), its successor-module Microsoft.Graph, or use the Graph REST API.

Since I’m already using the Az-module to deploy my Bicep-templates, I didn’t want to use another module and potentially deal with separate sign-in methods and tokens, so I decided to just call the Graph API directly:

# A list of all AAD permissions that should be granted for the managed identity
# https://learn.microsoft.com/en-us/graph/permissions-reference
$githubIdentityMsGraphPermissions = @(
    "Group.Read.All"
)

# This is a well-known ID for the MS Graph service principal
$msGraphSp = Get-AzAdServicePrincipal -ApplicationId "00000003-0000-0000-c000-000000000000"
# We're using the Az-module to aquire an access token for the Graph API
$graphAccessToken = Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com/"

# https://learn.microsoft.com/en-us/graph/api/resources/approleassignment
$apiUrl = "https://graph.microsoft.com/v1.0/servicePrincipals/$($githubIdentity.Id)/appRoleAssignments"

# We're only creating assignments that don't yet exist
$existingAssignments = Invoke-RestMethod -Uri $apiUrl -Method Get -Headers @{ Authorization = "Bearer $($graphAccessToken.Token)" }

foreach ($permissionName in $githubIdentityMsGraphPermissions) {
    #$permissionName = "Group.Read.All"
    $appRoleId = ($msGraphSp.AppRole | Where-Object { $_.Value -eq $permissionName } | Select-Object).Id

    $exists = $existingAssignments.value | Where-Object { $_.appRoleId -eq $appRoleId }
    if ($exists) {
        Write-Success "Permission '$permissionName' already exists"
    } else {
        $body = @{
            appRoleId = $appRoleId
            resourceId = $msGraphSp.Id
            principalId = $githubIdentity.Id
        }
        Invoke-RestMethod -Uri $apiUrl -Method Post -ContentType "application/json" `
            -Headers @{ Authorization = "Bearer $($graphAccessToken.Token)" } `
            -Body $($body | convertto-json) | Out-Null

        Write-Success "Permission '$permissionName' created"
    }
}

(Original source)

NOTE: To execute this step, you must have elevated permissions in Azure AD.

Creating a GitHub environment for the platform

My template uses GitHub environments to protect deployments to Azure.

As with all previous steps, this could be done manually via the UI, but I prefer automation and therefore create the environment via the script by using the GitHub CLI.

The GitHub CLI does not yet have support for environments, so we need to use gh api to call the GitHub REST API.

The script also uses a custom Exec-function (copied from psake) to fail the PowerShell script if the invocation of the native EXE fails (you’d have to always check $LastExitCode otherwise).

To create a GitHub environment, I’m using the following code:

$body = @{
  reviewers = @(
    @{ type = "User"; id = $ghUser.id }
  )
} | ConvertTo-Json -Compress

$ghEnv = Exec { $body | gh api "/repos/$($ghRepo.nameWithOwner)/environments/$environment" -X PUT -H "Accept: application/vnd.github+json" --input - } | ConvertFrom-Json

(Original source)

Creating the resource IDs as secrets in GitHub

While there are no passwords to authenticate GitHub with Azure, we still need to tell GitHub about the managed identity and its target tenant & subscription. We therefore need to store some IDs as GitHub secrets. These IDs will then be used by the GitHub workflows when running deployments to Azure.

Exec { gh secret set "AZURE_CLIENT_ID" -b $githubIdentity.AppId }
Exec { gh secret set "AZURE_SUBSCRIPTION_ID" -b $((Get-AzContext).Subscription.Id) }
Exec { gh secret set "AZURE_TENANT_ID" -b $((Get-AzContext).Subscription.TenantId) }

(Original source)

Using the managed identity in a GitHub workflow

With the preceding steps, the managed identity has been created, federated credentials have been assigned and GitHub has references to the required IDs as GitHub secrets. We’re therefore finally ready to do any further deployments via GitHub workflows.

My microservice template includes multiple GitHub workflows. There’s a workflow for each service, for shared environment resources, and for the shared platform resources.

We’ll look at the platform.yml workflow as an example for the following steps.

In order for GitHub-workflows to work with federated credentials, we must add permissions for the token:

permissions:
  id-token: write
  contents: read

(Original source)

We can then use azure/login to authenticate with Azure (using the previously created GitHub secrets):

    - uses: azure/login@v1
      with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
          # This allows us to use Azure PowerShell in addition to Azure CLI
          enable-AzPSSession: true

(Original source)

That’s it. Further calls via the Az-module should then be able to run successfully:

New-AzSubscriptionDeployment `
    -Location $config.location `
    -Name ("platform-" + (Get-Date).ToString("yyyyMMddHHmmss")) `
    -TemplateFile .\platform\main.bicep `
    -TemplateParameterObject @{
        deployGitHubIdentity = $false
    } `
    -Verbose | Out-Null

(Original source)

Feel free to start a discussion or create an issue in cwe1ss/msa-template if you have any feedback.

Does this result in a few failing requests until the load balancer has finally figured out that the instance is gone?

If so, this blog post might be for you!

Problem details

We are hosting our ASP.NET Core applications in Azure Service Fabric and public traffic is routed into the cluster via Azure Application Gateway.

Application Gateway doesn’t have a direct integration with Service Fabric’s naming resolution, so it can’t automatically forward traffic to the dynamic ports & nodes of a service in the cluster. Instead, we need to use fixed ports for our ASP.NET Core applications in Service Fabric and we use simple port based routing rules in Application Gateway.

Example: A stateless ASP.NET Core application fabric:/MyBlog/MyBlogWebsite is running in our Service Fabric cluster with a fixed port of 5000 and with InstanceCount=-1 (so it runs on each node). To expose this application, Application Gateway is configured to forward all requests targeting www.chwe.at to the fixed 5000-port on each node in the Service Fabric VMSS (virtual machine scale set).

This works great. However, during application updates, Service Fabric will stop the existing process before it starts the new application version. This is required because the port 5000 has to be released before it can be bound again to the new version. Application Gateway isn’t aware of this short termination, so any requests it forwards to the node during that time will fail.

Health checks to the rescue

Azure Application Gateway (and probably any other load balancer) supports health probes to decide if it should forward a request to a given node. In the simplest case, it will just periodically do a HTTP request to the root of your application and if it doesn’t receive a response or if the response returns a server error, it will take the instance out of rotation after a few failed attempts.

So if one of your application instances gets shut down, the load balancer will stop forwarding traffic to it after some time.

However, this still means that there will be failed requests until that has happened.

How can we improve this?

Should we change our deployment process and call an API of our load balancer to actively take the instance out of rotation before we do the update and call another API of the load balancer to take it back in once the new instance is running? This would definitely work, but unfortunately Azure Application Gateway doesn’t have such an API. We would also have to integrate this into every other orchestration action that results in instance shutdowns (scale down, move to another node, …).

Wouldn’t it be nice if we could just delay the shutdown of our instance and keep serving requests until the load balancer has figured out that it should take the instance out of rotation?

We can do this in ASP.NET Core by combining the following ideas:

• We need to expose the health status of the application on it’s own URL - e.g. /health
• With this separate URL, we can switch the health to Unhealthy, once the application receives a shutdown signal from the orchestrator (e.g. CTRL+C).
• We can now delay the shutdown until the load balancer health-timeout has been reached.
• Until then, we’ll just continue to serve any incoming requests.

You can find the finished code for this post here: https://github.com/cwe1ss/blog-zero-downtime-with-health-checks. If you want to follow along step by step, look at the separate commits. They area also linked in each step below.

Set up the /health-endpoint in ASP.NET Core

ASP.NET Core has a built-in feature for health checks.

To enable it, we need to register the feature with the DI container by calling services.AddHealhChecks() in Startup.ConfigureServices() and we need to enable the endpoint on the request pipeline by calling endpoints.MapHealthChecks("/health"); in the app.UseEndpoints(...)-block of Startup.Configure().

After this, we can run the app and navigate to http://localhost:5000/health. This will return the text “Healthy” and the status code 200.

See all changes from this step in the Git commit.

Add a health check that switches to Unhealthy, once the application shuts down

We can add our own health checks to the ASP.NET Core health system by implementing the interface Microsoft.Extensions.Diagnostics.HealthChecks.IHealthCheck.

To get notified when the application is being shut down, we can use Microsoft.Extensions.Hosting.IHostApplicationLifetime. This interface provides a ApplicationStopping-hook that is triggered when the shutdown signal is received but before the application stops processing requests!

When combined, we get the following first simple version of our ShuttingDownHealthCheck:

public class ShuttingDownHealthCheck : IHealthCheck
{
    private HealthStatus _status = HealthStatus.Healthy;

    public ShuttingDownHealthCheck(IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStopping.Register(() =>
        {
            Console.WriteLine("Shutting down");
            _status = HealthStatus.Unhealthy;
        });
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        var result = new HealthCheckResult(_status);
        return Task.FromResult(result);
    }
}

Our class also needs to be registered with the DI container by calling .AddCheck<ShuttingDownHealthCheck>("shutting_down") on the return object of services.AddHealthChecks().

However, it’s important to know that by default, ASP.NET Core initializes the class for every request to the health endpoint. This doesn’t work for our scenario as we need the global _status variable and just a single ApplicationStopping-registration.

To ensure the class is created only once, we have to add it as a singleton to the DI framework via services.AddSingleton<ShuttingDownHealthCheck>();.

It’s also important to know, that our ShuttingDownHealthCheck-class will only be initialized, when it is requested for the first time. So if we just run the app, navigate to http://localhost:5000 and press CTRL+C, our “Shutting down” message will NOT appear in the console.

If we navigate to http://localhost:5000/health and press CTRL+C afterwards, the “Shutting down” message will appear on the console!

This behavior is fine for our scenario as the load balancer will continuously invoke this endpoint anyway!

See all changes from this step in the Git commit.

Delay the shutdown

If you’ve followed the steps so far, you will have noticed that the application still shuts down immediately after “Shutting down” has been printed to the console.

To delay the shutdown, we can simply add a Thread.Sleep() to the code in our ApplicationStopping-handler. With this, the main thread is blocked but regular requests will still be processed on other threads.

Let’s add Thread.Sleep(TimeSpan.FromSeconds(15)); after our _status = HealthStatus.Unhealthy; statement and run the app again.

If we now navigate to http://localhost:5000/health and press CTRL+C afterwards, our “Shutting down” message will appear on the console and the application will keep running!

Any request to the /health-endpoint during that time will now return “Unhealthy” with a status code 503 (Service unavailable).

When deployed, the load balancer will now receive this Unhealthy response and take the instance out of rotation after a few attempts. Until then, any regular requests it sends to the instance will still be processed!

Improve the health check

There’s still a few issues with our custom health check:

• ASP.NET Core has a default shutdown timeout of 5 seconds. After this, it will throw an OperationCanceledException and therefore not gracefully shutdown other background services etc.
• The shutdown delay is annoying during development as we now can’t quickly close the app.
• Our “Shutting down” message is just printed to the console. It would be nice if it were sent to the regular logging system.

To increase the ASP.NET Core ShutdownTimeout, we need to configure the HostOptions class in Startup.ConfigureServices():

services.Configure<HostOptions>(option =>
{
    option.ShutdownTimeout = System.TimeSpan.FromSeconds(30);
});

To improve our health check, we’ll introduce IHostEnvironment to detect if we’re running in Production-mode and an ILogger. Our ApplicationStopping-registration will now look like this:

appLifetime.ApplicationStopping.Register(() =>
{
    _status = HealthStatus.Unhealthy;

    bool delayShutdown = _hostEnvironment.IsProduction();
    if (delayShutdown)
    {
        var shutdownDelay = TimeSpan.FromSeconds(25);

        _logger.LogInformation(
            "Delaying shutdown for {Seconds} seconds",
            shutdownDelay.TotalSeconds);

        // ASP.NET Core requests are processed on separate threads,
        // so we can just put the main thread on sleep.
        Thread.Sleep(shutdownDelay);

        _logger.LogInformation("Shutdown delay completed");
    }
});

Of course, it would also be possible to just skip the registration ouf our health check in the Startup.ConfigureServices()-method.

The logic in our ASP.NET Core application is now finished!

See all changes from this step in the Git commit.

Set the load balancer settings

It’s important to understand that we’ve set a 25 second shutdown delay. This means, the load balancer must take the instance out of rotation before that time. If it fails to do so, there will be failed requests again.

We therefore need to set up our load balancing probes e.g. in the following way:

• Target URL: /health
  • Our custom health endpoint
• Interval: 5 seconds
  • Run the probe every 5 seconds
• Timeout: 4 seconds
  • If the service doesn’t respond, fail after 4 seconds
• Attempts: 3
  • Take the service out of rotation after 3 failed attempts

With these settings, the load balancer will take the service out of rotation after 15-20 seconds!

Of course, you can change these settings to whatever fits your scenario best.

Summary

This post is quite long as it tries to explain everything step by step, but in general, the idea is very simple:

• We use a custom health check to mark the instance as Unhealthy once the shutdown has been requested
• We delay the shutdown for 25 seconds. Any regular requests will still be processed during that time.
• We make sure the load balancer takes the instance out of rotation before these 25 seconds are over.

You can find the code for this blog here: https://github.com/cwe1ss/blog-zero-downtime-with-health-checks.

Follow the commits to see the separate steps we’ve taken.

• Our Flutter app should target iOS and Android.
• We want a DEV version and a LIVE version of our app, each targeting a different API URL.
• Developers should never have to manually change any code to switch between the environments.
• We want to be able to have the DEV app and the LIVE app installed on the same device at the same time.

The best way to solve these requirements in Flutter is to use flavors. There are also some other tutorials for this linked on the official Flutter docs which might be helpful.

The code for this guide is stored on GitHub and changes for each section are separate commits that are linked in the section below.

As we need to change settings in XCode, we need a Mac with Android Studio and XCode for this tutorial.

You also need to have Flutter installed already. Follow the Getting started-docs if you still need to install it.

I’m using Flutter v1.22.0 for this tutorial.

Create the Git repository and clone it locally

Create a new Git repository. Mine is: https://github.com/cwe1ss/flutter-flavors-ci-cd

git clone https://github.com/cwe1ss/flutter-flavors-ci-cd.git
cd flutter-flavors-ci-cd/

Create the Flutter app

Let’s get started by creating the Flutter app, named flutter_flavors via the Flutter CLI directly in the root folder of our repository:

flutter create --project-name flutter_flavors .

Run the app on an Android device/emulator to ensure it works.

See all changes from this step in the Git commit.

Add a Flutter build configuration for each flavor in Android Studio

We want to have two flavors called dev and live.

If you want to launch a flutter app with a flavor, you have to use the --flavor NAME parameter in the Flutter CLI. To automatically start the app with a flavor in Android Studio we need to change the build configurations:

• Find main.dart in the Android Studio top toolbar and select Edit Configurations.... This opens the “Run/Debug Configurations” window.
• Change the Name: field to dev
• For Build flavor: set dev as well.
• Make sure “Share through VCS” is selected.
• Copy the dev configuration (It’s an icon in the top left of the window)
• Change the Name: and Build flavor: values to live
• Make sure “Share through VCS” is selected as well
• Close the dialog. Instead of “main.dart”, it will now display “dev” in the top toolbar.

IMPORTANT: Flavor names may not start with “test” as that’s not allowed by Android.

Add the build configurations to Git

When you select “Share through VCS”, Android studio will create files in the .idea/runConfigurations folder, however they’ll be ignored by the existing .gitignore file.

We’ll therefore add these files manually to Git, so that other users in the team can use it as well:

git add .idea/runConfigurations/dev.xml -f
git add .idea/runConfigurations/live.xml -f
git commit -m 'Persist flutter build configurations'

See all changes from this step in the Git commit.

Set up flavors for Android

In order to actually use different flavors, we need to set them up in the lib-folder and in each platform (android, ios).

We’ll start with the android part.

Add the method channel in Android code

When the app starts, Flutter needs a way to ask the native platform which flavor it has been started with. To communicate with native code, Flutter uses method channels.

Go to android/app/src/main/kotlin/com.example.flutter_flavors and replace everything except the first line (the package import) with the following code. This will set up the method channel that returns the BuildConfig.FLAVOR value, which is a built-in value of Android.

import androidx.annotation.NonNull;
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel
import io.flutter.plugins.GeneratedPluginRegistrant

class MainActivity: FlutterActivity() {
    override fun configureFlutterEngine(@NonNull flutterEngine: FlutterEngine) {
        GeneratedPluginRegistrant.registerWith(flutterEngine);

        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "flavor").setMethodCallHandler {
            call, result -> result.success(BuildConfig.FLAVOR)
        }
    }
}

Add the flavor-settings to the Android build config

In Android, the native flavor-specific values are stored in android/app/src/build.gradle via the android.flavorDimensions and android.productFlavors keys.

We’ll use these keys to set up the flavor-specific applicationId and the flavor-specific display name for the app. This is important because we want to be able to have both flavors of the app installed at the same time.

The applicationId is the unique app id for each flavor in the Google Play store. Once deployed to Google Play, this can not be changed anymore!

Therefore, add the following two things within the android { ... } section:

android {
    // ... all existing things like `sourceSets`, ...

    flavorDimensions "app"

    productFlavors {
        dev {
            dimension "app"
            applicationId "at.chwe.flutterflavors.dev"
            resValue "string", "app_name", "DEV Flutter Flavors"
        }
        live {
            dimension "app"
            applicationId "at.chwe.flutterflavors"
            resValue "string", "app_name", "Flutter Flavors"
        }
    }
}

Use the app_name in the AndroidManifest.xml

The applicationId is a well-known key that will already be used when the app is launched with a given flavor.

However, we’ll need to do some more work to get the app_name working: Open android/app/src/main/AndroidManifest.xml and replace the <application android:label="flutter_flavors" /> key with <application android:label="@string/app_name" />.

Run the app again on Android

As we’re now using new applicationIds, make sure the existing “flutter_flavors”-app is uninstalled from your device.

Now, launch the app in Android Studio with the “dev” build configuration.

Close the app in the device and check your application list, the app name will now display “DEV Flutter Flavors”!

Stop the app in Android Studio, change the build configuration to “live” and launch the app again.

You’ll now have both flavors of your app installed on your Android device!

Our native Android configuration is now complete.

See all changes from this step in the Git commit.

Get the flavor in our Flutter code

As described in our requirements, we want to target different API endpoints per flavor so we need a way to get the current flavor in our Flutter code.

We’ll first add a class called FlavorSettings in a new file called lib/flavor_settings.dart that will hold all of our flavor-specific settings that we only need in our Flutter code:

/// Contains the hard-coded settings per flavor.
class FlavorSettings {
  final String apiBaseUrl;
  // TODO Add any additional flavor-specific settings here.

  FlavorSettings.dev()
    : apiBaseUrl = 'https://dev.flutter-flavors.chwe.at';

  FlavorSettings.live()
    : apiBaseUrl = 'https://flutter-flavors.chwe.at';
}

Next, we’ll use this in main.dart, where we’ll read the flavor via our method channel from the native platform and we’ll create the corresponding FlavorSettings-object. We’ll also have to make our main-method async for that.

When done, your main.dart should contain the following code before the class MyApp extends StatelessWidget { line:

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

import 'flavor_settings.dart';

Future<void> main() async {
  // NOTE: This is required for accessing the method channel before runApp().
  WidgetsFlutterBinding.ensureInitialized();

  final settings = await _getFlavorSettings();
  print('API URL ${settings.apiBaseUrl}');

  runApp(MyApp());
}

Future<FlavorSettings> _getFlavorSettings() async {
  String flavor = await const MethodChannel('flavor')
        .invokeMethod<String>('getFlavor');

  print('STARTED WITH FLAVOR $flavor');

  if (flavor == 'dev') {
    return FlavorSettings.dev();
  } else if (flavor == 'live') {
    return FlavorSettings.live();
  } else {
    throw Exception("Unknown flavor: $flavor");
  }
}

// ... class MyApp extends StatelessWidget {

Run the app with dev build configuration and look at the console output. It will display the following statements:

I/flutter ( 4458): STARTED WITH FLAVOR dev
I/flutter ( 4458): API URL https://dev.flutter-flavors.chwe.at

Switch to the live build configuration and run your app again. This time, the console will display the following statements:

I/flutter ( 4615): STARTED WITH FLAVOR live
I/flutter ( 4615): API URL https://flutter-flavors.chwe.at

That’s it! We can now access the current flavor from within Flutter and we can have flavor-specific settings.

You can pass the FlavorSettings-instance down to your widgets manually, or you can use e.g. the provider-package to access it via dependency injection in your widgets.

See all changes from this step in the Git commit.

Set up flavors for iOS

Unfortunately, setting up flavors in iOS is more complex and we’ll have to use XCode and its UI for most of the steps.

Let’s try building our app with a flavor for iOS now to see, what kind of error we get:

flutter build ios --flavor dev

The Xcode project does not define custom schemes. You cannot use the --flavor option.

This means, that on iOS we have to rely on a feature called “custom schemes” to represent our flutter flavors. Setting them up requires multiple steps.

Create custom build configurations for the flavors

Let’s open our ios-folder in XCode and start by creating our custom build configurations:

• Make sure the root “Runner” node is selected in XCode
• In the main window, select the “Runner” node below “PROJECT” (NOT below TARGETS)
• Select the “Info” tab
• In the “Configurations” section, do the following:
  • Rename “Debug” to “Debug-dev”
  • Rename “Release” to “Release-dev”
  • Rename “Profile” to “Profile-dev”
  • Duplicate “Debug-dev” and rename it to “Debug-live”
  • Duplicate “Release-dev” and rename it to “Release-live”
  • Duplicate “Profile-dev” and rename it to “Profile-live”

This means, for every flavor, we need a separate “Debug”, “Release” & “Profile” configuration.

Assign build configurations to custom schemes

Now we can set up the actual “custom schemes” by doing the following:

• Make sure the root “Runner” node is selected in XCode
• Select “Product -> Scheme -> Manage Schemes…” in the main toolbar.
• To get the “dev” scheme:
  • Select the “Runner” scheme, click on the settings-icon in the top left and select “Duplicate”
  • Rename the scheme to “dev”
  • Make sure “Shared” is selected
  • Close the dialog
• To get the “live” scheme:
  • Select the “Runner” scheme again, click on the settings-icon in the top left and select “Duplicate”
  • Rename the scheme to “live”
  • For each of the sections (“Run”, “Test”, “Profile”, “Analyze”, “Archive”) on the left, change the build configuration to the corresponding “-live” version.
  • Make sure “Shared” is selected
  • Close the dialog

Back in the “schemes” list, you can now delete the existing “Runner” scheme. This should result in the list looking like this:

Adding the method channel for iOS

Building the app now shoud succeed, however when you try to run it, it will fail with the following error:

[VERBOSE-2:ui_dart_state.cc(177)] Unhandled Exception: MissingPluginException(No implementation found for method getFlavor on channel flavor)

That’s because we haven’t yet implemented the method channel that Flutter uses to get the current flavor from the native platform.

To add this, we need to add some code to the application()-function of the Runner/AppDelegate.swift-file in XCode. The finished file should look like this:

import UIKit
import Flutter

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)

    let controller = window.rootViewController as! FlutterViewController

    let flavorChannel = FlutterMethodChannel(
        name: "flavor",
        binaryMessenger: controller.binaryMessenger)

    flavorChannel.setMethodCallHandler({(call: FlutterMethodCall, result: @escaping FlutterResult) -> Void in
        // Note: this method is invoked on the UI thread
        let flavor = Bundle.main.infoDictionary?["App - Flavor"]
        result(flavor)
    })

    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

This will set up a method channel handler that reads the current flavor from a Bundle.main.infoDictionary with a key called App - Flavor.

Set up the flavor value per scheme

The Bundle.main.infoDictionary from before refers to the Runner/Info.plist file and App - Flavor is a custom key that we have to add there manually next.

So open the Runner/Info.plist file in XCode and and add a new row with the following settings:

• Key: App - Flavor
• Type: String
• Value $(APP_FLAVOR)

We now have the key but we still don’t have the actual flavor-specific values per scheme. To add them, we now have to do the following:

• Select the root “Runner” node in your XCode project structure
• Select “Runner” below TARGETS
• Select the “Build settings” tab
• Click on the + to add a new User-defined setting
• Name it APP_FLAVOR
• Expand the node by clicking on the little arrow on the left of the row and add the actual flavor value to each build configuration:
  • Debug-dev: dev
  • Debug-live: live
  • Profile-dev: dev
  • Profile-live: live
  • Release-dev: dev
  • Release-live: live

When done, it should look like this:

Run the iOS app

We should now be able to select the “dev”-scheme in the top navigation bar of XCode and run the app.

NOTE: If you get weird build errors from XCode, try switching between the dev/live schemes or try restarting XCode or running the iOS app from Android Studio.

You should now see similar console output like for the Android app:

2020-10-03 14:44:05.525493+0200 Runner[26055:336596] flutter: STARTED WITH FLAVOR dev
2020-10-03 14:44:05.526672+0200 Runner[26055:336596] flutter: API URL https://dev.flutter-flavors.chwe.at

See all changes from this step in the Git commit.

Great, we now have set up our flavors for iOS as well!

Set the bundle id and app name per flavor for iOS

You might have noticed that the app name on the iPhone still is “flutter_flavors”. Also, when you run both flavors, you still only have one app on your phone:

Remember, that for Android we’ve set those values in the build.gradle file.

To make things flavor-specific in iOS, we need to do something similar like we’ve done for the flavor value itself, where we’ve configured a key in Info.plist and then set different values in the “TARGETS/Runner -> Build Settings” tab.

Set the flavor-specific bundle identifier

The Info.plist file already contains a key named Bundle identifier that already contains a dynamic value $(PRODUCT_BUNDLE_IDENTIFIER), so we don’t have to create another entry in this file.

Instead, we just have to modify this key in the the build settings:

• In XCode, select the root “Runner” node in the project explorer
• Select “Runner” below TARGETS
• Go to the “Build Settings” tab
• In the “Packaging” section, find the “Product Bundle Identifier” key
• Expand the key by clicking on the small arrow on the left
• Set the value per build configuration:
  • Debug-dev: at.chwe.flutterflavors.dev
  • Debug-live: at.chwe.flutterflavors
  • Profile-dev: at.chwe.flutterflavors.dev
  • Profile-live: at.chwe.flutterflavors
  • Release-dev: at.chwe.flutterflavors.dev
  • Release-live: at.chwe.flutterflavors

Set the app name

To have separate display names per flavor, do the following:

• In XCode, select the root “Runner” node in the project explorer
• Select “Runner” below TARGETS
• Select the “Info” tab
• Change the value of the key Bundle name to $(APP_NAME).
• Go to the “Build Settings” tab
• Add a new User-Defined setting
• Name it APP_NAME
• Expand the APP_NAME-node by clicking on the small arrow on the left side of the node.
• Set the value per build configuration:
  • Debug-dev: DEV Flutter Flavors
  • Debug-live: Flutter Flavors
  • Profile-dev: DEV Flutter Flavors
  • Profile-live: Flutter Flavors
  • Release-dev: DEV Flutter Flavors
  • Release-live: Flutter Flavors

Run the app again with the dev and live flavors

Delete the existing “flutter_flavors” app from your iPhone and run it again with each flavor. You should now have both apps with the correct name on your phone:

See all changes from this step in the Git commit.

Add your own flavor-specific settings

If you need another flavor-specific setting, you have to know if it is a platform-specific setting, that needs to be integrated directly into the android and ios folders or if it is a setting that is only required in your Flutter code.

For platform-specific settings, the above guides for setting the app name and bundle id should help.

For settings that you only need in your Flutter-code, just add them to the FlavorSettings-class that we’ve created above.

Summary

We’ve now set up our Flutter project to have multiple flavors. We use those flavors to separate our app environments (DEV & LIVE). This way we don’t need to e.g. manually comment out code to switch our API URL or any other settings. We can also have both versions installed side by side, which makes development and support much easier as we can develop on the DEV version while we still can use the LIVE version which is deployed to the stores.

ProjectsMissingInSolution.ps1

This small program helps you by showing you all csproj-files that are not part of your solution file!

class Program
{
    static void Main(string[] args)
    {
        // Parameters
        string baseFolder = @"C:\path\to\solution\";
        string slnFile = "AllProjects.sln";
        string outputFile = "MissingProjects.txt";

        string slnContent = File.ReadAllText(Path.Combine(baseFolder, slnFile));

        string[] projectFiles = Directory.GetFiles(baseFolder, "*.csproj", SearchOption.AllDirectories);

        List<string> missingProjects = projectFiles
            .Where(fullPath => slnContent.IndexOf(fullPath.Replace(baseFolder, ""), StringComparison.OrdinalIgnoreCase) < 0)
            .ToList();

        File.WriteAllLines(outputFile, missingProjects);

        Console.WriteLine("Projects missing in solution: " + missingProjects.Count);
        Console.WriteLine("Details: " + outputFile);
        Console.ReadLine();
    }
}

• (Project Root)
  • Areas
    • (AreaName)
      • (FeatureName)
        • (FeatureName)Controller.cs
        • Index.cshtml
        • Edit.cshtml
      • … (other features)
      • Shared
        • … (area specific shared views like EditorTemplates, Layout-pages, …)
    • … (other areas)
    • Shared
      • … (area independent shared views like EditorTemplates, Layout-pages, …)
  • Features
    • (Feature2Name)
      • (Feature2Name)Controller.cs
      • Index.cshtml
      • Edit.cshtml
    • … (other features)
    • Shared
      • … (feature independent shared views like EditorTemplates, Layout-pages, …)

Of course, if you don’t want to use “areas” you only need the “Features” folder in your project. This also means, that if you move to this new structure, you can completely remove the old “Controllers” and “Views” folders.

Controllers

To support this structure for Controllers, you don’t have to change anything in MVC since it does not force you to place them in a special folder! You can put Controllers into whatever folder you want. Resolving them is purely depended on your RouteConfig.

Views

To support this structure for Views, you have to create a custom ViewEngine. As you can see in the following example, this can also be done very easily. Please note, that this code only supports *.cshtml-files. If you want to use *.vbhtml-files as well, you just have to duplicate the paths and change the extension to *.vbhtml.

public class FeatureFolderViewEngine : RazorViewEngine
{
    public FeatureFolderViewEngine()
    {
        // {0} ActionName
        // {1} ControllerName
        // {2} AreaName

        AreaViewLocationFormats = new[]
                                {
                                    "~/Areas/{2}/{1}/{0}.cshtml",
                                    "~/Areas/{2}/Shared/{0}.cshtml",
                                    "~/Areas/Shared/{0}.cshtml",
                                };

        AreaMasterLocationFormats = new[]
                                    {
                                        "~/Areas/{2}/{1}/{0}.cshtml",
                                        "~/Areas/{2}/Shared/{0}.cshtml",
                                        "~/Areas/Shared/{0}.cshtml",
                                    };

        AreaPartialViewLocationFormats = new[]
                                        {
                                            "~/Areas/{2}/{1}/{0}.cshtml",
                                            "~/Areas/{2}/Shared/{0}.cshtml",
                                            "~/Areas/Shared/{0}.cshtml",
                                        };

        ViewLocationFormats = new[]
                            {
                                "~/Features/{1}/{0}.cshtml",
                                "~/Features/Shared/{0}.cshtml",
                            };

        MasterLocationFormats = new[]
                                {
                                    "~/Features/{1}/{0}.cshtml",
                                    "~/Features/Shared/{0}.cshtml",
                                };

        PartialViewLocationFormats = new[]
                                    {
                                        "~/Features/{1}/{0}.cshtml",
                                        "~/Features/Shared/{0}.cshtml",
                                    };

        FileExtensions = new[]
                        {
                            "cshtml",
                        };
    }
}

Of course, if you use this new structure, you lose some of the built-in templating- and navigation-support in Visual Studio since VS does not recognize these folders as “Views”-folders. Therefore, the following things no longer work:

• “Go To View” throws an error.
• “Add View” adds the view to the old “Views”-folder.

Fortunately, ReSharper helps you with these issues since it contains built-in templates for views and also supports our custom ViewEngine!

Which of these requirements is more common?

• Change something in every view, controller or model of your project
• Add a new field to your model X, show this field to the user, make it editable, the value must be validated against some fancy rules, …

I guess we are on the same page if we see the second one as more common. I would go as far as to say that if you have the first requirement you’re either working on a major relaunch or you’re not using layout pages, css, abstract classes, [insert random reusability gadget here] correctly.

By default, the ASP.NET MVC project structure advices you to keep every concept in its own area – you therefore might end up with a structure like this:

• Content
  • CustomerImages
    • AnIconSpecialToCustomers.png
  • Customers.css
• Controllers
  • CustomersController.cs
• Models
  • Customer.cs
• Repositories
  • CustomerRepository.cs
• Scripts
  • Customers.js
• Views
  • Customers
    • Create.cshtml
    • Index.cshtml
• ViewModels
  • Customers
    • IndexViewModel.cs
    • CreateViewModel.cs

As soon as you have more than 3 controllers, this becomes hard to navigate. ASP.NET MVC’s solution for having a better structure is to use “Areas”, however in my opinion they do not solve the problem I’m talking about. To complete the second requirement I’ve mentioned, you still have to navigate through many folders, because most probably, you don’t have a distinct views-guy, a distinct model-guy, a distinct controller-guy, … in your company. It’s a lot more common that e.g. only one or two people are working on all of these mentioned files.

Grouping files by feature

When I’m talking about a feature, I understand it as a sum of files that are needed to create a user benefit. Therefore, with structuring files by feature, the project structure could look like this:

• Customers
  • Images
    • AnIconSpecialToCustomers.png
  • Create.cshtml
  • CreateViewModel.cs
  • Customer.cs
  • CustomerRepository.cs
  • Customers.css
  • Customers.js
  • CustomersController.cs
  • Index.cshtml
  • IndexViewModel.cs

Think again of our second requirement and of some of the advantages with this structure:

• You immediately get an overview about how the feature might be implemented.
• You immediately see which files might be affected by the requirement. You don’t have to check every concept folder to see if there even is a corresponding file. (there might not be a js-file for every feature, …)
• Every affected file is in one folder. The required navigation in the Solution Explorer is kept to a minimum.
• In your source control system, you can look at the entire change history of this feature on one folder.
• If you have to implement a new similar feature, you can copy this one folder and use it as a starting point.
• …

Why is there a M in ASP.NET MVC?

I would like to make an exception of my previous structure: It’s important to understand that the ASP.NET MVC framework itself (System.Web.Mvc) does NOT give you any built-in support for “models”. If you require persistent data, you are allowed to use whatever technology you want (Entity Framework, NHibernate, raw ADO.NET, …). Yes, the project templates by default already reference Entity Framework, but again, this is a separate library and ASP.NET MVC has no dependency on it.

In my opinion this is a very good thing! The traditional three-tier architecture (data, business logic, presentation) still is one of the most important concepts for structuring software systems. ASP.NET MVC clearly targets the presentation tier and shouldn’t cover responsibilities from other tiers.

For this reason, we have to move the files “Customer.cs” and “CustomerRepository.cs” into a separate library. However, everything else in our folder belongs to the presentation layer.

What’s next?

I plan to do follow-up posts that address the challenges and also possible solutions for this structure, so stay tuned!

Get a running BlogEngine.NET instance within minutes

I was always interested in Windows Azure Microsoft Azure but never really had the time to do something useful with it. Therefore I decided to take this opportunity and move my blog to it. I already had access to the Azure Management Portal, so I didn’t have to go through some registration process. Since I also wanted to update my blog to the latest version of BlogEngine.NET I decided to start with a new installation and migrate my data afterwards (moving data from 6 posts is not so hard :-) ). Luckily, with Azure’s Gallery, it’s extremely easy to setup an instance of BlogEngine.Net. I just followed these instructions: http://blogs.msdn.com/b/webdev/archive/2012/10/12/blogengine-net-and-windows-azure-web-sites.aspx

After that, I just had to go through a quick export/import process to move my data from my old blog to the new one. I started with a “free” web site but quickly scaled it up to a “shared” one because I wanted the site to be running on my custom domain.

Deployment with Git and the App_Data folder

The default template of BlogEngine.NET 2.9 is quite nice, however I wanted to make some minor changes. Sounds like a good opportunity to test another great feature of Microsoft Azure: Git deployment.

According to this tutorial, I setup a Git repository for my web site within the Azure portal and cloned the repository to my notebook. Again, this was very straightforward and worked immediately. This also has the advantage that you now have a backup of your remote files on your home network.

But there’s one important thing to take care of when you use Git deployment with BlogEngine.NET. BlogEngine.NET by default stores data in files within the App_Data folder. This is quite nice since you don’t have to pay for a SQL Server database! However, if you use Git deployment it overwrites this folder, since it’s now under source control. Therefore I added the “App_Data” folder to the .gitignore file. Unfortunately, the deployment still did overwrite changes. I guess this happened, because on the server, the App_Data folder was still a part of the git folder.

To overcome this, I tried a different way: First, I copied my local App_Data folder to some backup directory on my notebook. Then I removed the .gitignore file and really deleted the App_Data folder from my local and remote repository (so if you do this as well, please note that you will have a downtime!). After that, I manually copied the App_Data folder back to Azure with FTP. As a last step, I re-created the .gitignore file with the App_Data-exclusion and also moved the App_Data folder back on my machine.

As a result, the “App_Data” folder is no longer monitored by Git and will not be touched when Azure does a deployment. Of course, whenever you need a up-to-date version of your App_Data folder on your PC for development purposes, you have to manually download it from Azure.

Some warnings about this

• I’m pretty sure this is not the best way to handle this. As far as I know, you shouldn’t store user generated content on your server but instead use an Azure Storage account for it. Having user files on your server has several disadvantages: you can’t scale out your servers, you don’t have any replication or backups and so on.
• I’m not sure if the current deployment behavior, which does not touch untracked folders will stay that way forever. I wouldn’t be surprised if they do a real sync someday because actually, the git repository should be 100% consistent with the web folder.

This means, I do not recommend this for anything else than completely uncritical things! If you want to do this, make sure you regularly backup your App_Data folder by e.g. doing a scheduled FTP download every day.

For this blog, I’m fine with those risks for now but if I happen to need a storage account anyway or if I will blog more in the future I will definitely move the data to a storage account.

http://www.microsoft.com/downloads/details.aspx?FamilyID=53289097-73ce-43bf-b6a6-35e00103cb4b&displaylang=en

Next week, I will attend the biggest German .NET conference BASTA! Spring 2009. Feel free to contact me, if you’d like to chat with me “offline” there!

What’s next on my blog?

I’m working on an ASP.Net MVC application right now and I plan to post about some of the techniques I’ve used, so expect to read from me after the conference!

Thanks for reading,
Christian Weiss