JSON Platform Bundle

The JSON Platform Bundle provider allows you to use appsettings.json files just like ASP.NET Core, but from platform-specific bundled locations. This is especially useful for whitelabelling - you can unpack, edit, and repack the JSON config without triggering a rebuild.

Setup

1. Install the NuGet package

2. Create an appsettings.json file in your project.

   Android

   Place the file in the Assets folder. Ensure the build action is set to AndroidAsset.

   iOS / Mac Catalyst

   Place the file in the root of your project. Ensure the build action is set to BundleResource.

3. Add the provider to your configuration builder:

   var config = new ConfigurationBuilder()
       .AddJsonPlatformBundle()
       .Build();

   You can also pass an environment name to enable environment-specific overrides:

   var config = new ConfigurationBuilder()
       .AddJsonPlatformBundle("DEBUG")
       .Build();

Platform File Merge Priority

The provider automatically looks for platform-specific appsettings files and merges them with the base appsettings.json. The naming convention is:

appsettings.[platform].[environment].json

Where [platform] can be: ios, maccatalyst, apple (both iOS & Mac Catalyst), or android.

iOS / Mac Catalyst

Files are merged in this priority (highest to lowest):

1. appsettings.ios.[environment].json (or maccatalyst)
2. appsettings.ios.json (or maccatalyst)
3. appsettings.apple.[environment].json
4. appsettings.apple.json
5. appsettings.[environment].json
6. appsettings.json

Android

Files are merged in this priority (highest to lowest):

1. appsettings.android.[environment].json
2. appsettings.android.json
3. appsettings.[environment].json
4. appsettings.json

If any file does not exist, it is simply skipped.

Project File Setup

Ensure your project file includes the appropriate build actions for your config files:

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">
    <AndroidAsset Include="appsettings.json" />
    <AndroidAsset Include="appsettings.android.json" Condition="Exists('appsettings.android.json')" />
</ItemGroup>

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios' Or $([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">
    <BundleResource Include="appsettings.json" />
    <BundleResource Include="appsettings.apple.json" Condition="Exists('appsettings.apple.json')" />
</ItemGroup>