AggregateConfigBuildTask

AggregateConfigBuildTask is an MSBuild task that aggregates and transforms configuration files into more consumable formats like JSON, Azure ARM template parameters, YAML during the build process.

Links

• NuGet.org: https://www.nuget.org/packages/AggregateConfigBuildTask
• GitHub: https://github.com/richardsondev/AggregateConfigBuildTask

Features

• Merge multiple configuration files into a single output format (JSON, Azure ARM parameters, or YAML).
• Support for injecting custom metadata (e.g., ResourceGroup, Environment) into the output.
• Optionally include the source file name in each configuration entry.
• Embed output files as resources in the assembly for easy inclusion in your project.

Installation

To install the AggregateConfigBuildTask NuGet package, run the following command:

dotnet add package AggregateConfigBuildTask

Alternatively, add the following line to your .csproj file:

<PackageReference Include="AggregateConfigBuildTask" Version="{latest}" />

{latest} can be found here.

Parameters

Parameter	Description	Supported Values	Default
OutputFile (Required)	The file path to write output to. Should include the extension.
OutputType (Required)	Specifies the format of the output file.	Json, Arm, Yaml
InputDirectory (Required)	The directory containing the files that need to be aggregated.
InputType	Specifies the format of the input files. Refer to the File Types table below for the corresponding file extensions that will be searched for.	Json, Arm, Yaml	Yaml
AddSourceProperty	Adds a source property to each object in the output, specifying the filename from which the object originated.	true, false	false
AdditionalProperties	A set of custom top-level properties to include in the final output. Use ItemGroup syntax to define key-value pairs.
IsQuietMode	When true, only warning and error logs are generated by the task, suppressing standard informational output.	true, false	false

File Types

File Type	Extensions
Json	.json
Arm	.json
Yaml	.yml, .yaml

Usage

Basic Example

In your .csproj file, use the task to aggregate YAML files and output them in a specific format. Here’s an example of aggregating YAML files and generating JSON output:

<Project Sdk="Microsoft.NET.Sdk">

  <Target Name="AggregateConfigs" BeforeTargets="PrepareForBuild">
    <ItemGroup>
      <AdditionalProperty Include="ResourceGroup=TestRG" />
      <AdditionalProperty Include="Environment=Production" />
    </ItemGroup>

    <AggregateConfig 
      InputDirectory="Configs"
      OutputFile="$(MSBuildProjectDirectory)\out\output.json"
      AddSourceProperty="true"
      InputType="Yaml"
      OutputType="Json"
      AdditionalProperties="@(AdditionalProperty)" />
  </Target>

</Project>

In this example:

• The Configs directory contains the YAML files to be aggregated.
• The output will be generated as out/output.json.
• The AddSourceProperty flag adds the source file name to each configuration entry.
• The AdditionalProperties are injected into the top-level of the output as custom metadata.

ARM Template Parameters Output Example

You can also generate Azure ARM template parameters. Here's how to modify the configuration to output in the ARM parameter format:

<Project Sdk="Microsoft.NET.Sdk">

  <Target Name="AggregateConfigsForARM" BeforeTargets="PrepareForBuild">
    <ItemGroup>
      <AdditionalProperty Include="ResourceGroup=TestRG" />
      <AdditionalProperty Include="Environment=Production" />
    </ItemGroup>

    <AggregateConfig 
      InputDirectory="Configs"
      OutputFile="$(MSBuildProjectDirectory)\out\output.parameters.json"
      OutputType="Arm"
      AdditionalProperties="@(AdditionalProperty)" />
  </Target>

</Project>

YAML Output Example

You can also output the aggregated configuration back into YAML format:

<Project Sdk="Microsoft.NET.Sdk">

  <Target Name="AggregateConfigsToYAML" BeforeTargets="PrepareForBuild">
    <ItemGroup>
      <AdditionalProperty Include="ResourceGroup=TestRG" />
      <AdditionalProperty Include="Environment=Production" />
    </ItemGroup>

    <AggregateConfig 
      InputDirectory="Configs"
      OutputFile="$(MSBuildProjectDirectory)\out\output.yaml"
      OutputType="Yaml"
      AdditionalProperties="@(AdditionalProperty)" />
  </Target>

</Project>

Embedding Output Files as Resources

You can embed the output files (such as the generated JSON) as resources in the assembly. This allows them to be accessed from within your code as embedded resources.

<Project Sdk="Microsoft.NET.Sdk">

  <Target Name="AggregateConfigs" BeforeTargets="PrepareForBuild">
    <ItemGroup>
      <AdditionalProperty Include="ResourceGroup=TestRG" />
      <AdditionalProperty Include="Environment=Production" />
    </ItemGroup>

    <AggregateConfig 
      InputDirectory="Configs"
      OutputFile="$(MSBuildProjectDirectory)\out\output.json"
      OutputType="Json"
      AdditionalProperties="@(AdditionalProperty)" />

    <!-- Embed output.json as a resource in the assembly -->
    <ItemGroup>
      <EmbeddedResource Include="$(MSBuildProjectDirectory)\out\output.json" />
    </ItemGroup>
  </Target>

</Project>

In this example:

• The generated output file output.json is embedded in the resulting assembly as a resource.
• You can access this resource programmatically using the System.Reflection API.

Example YAML Input

Assume you have the following YAML files in the Configs directory:

resources:
  - id: "Resource1"
    type: "Compute"
    description: "Main compute resource"

resources:
  - id: "Resource2"
    type: "Storage"
    description: "Storage resource"

Output JSON Example

{
  "resources": [
    {
      "id": "Resource1",
      "type": "Compute",
      "description": "Main compute resource",
      "source": "file1"
    },
    {
      "id": "Resource2",
      "type": "Storage",
      "description": "Storage resource",
      "source": "file2"
    }
  ],
  "ResourceGroup": "TestRG",
  "Environment": "Production"
}

ARM Parameter Output Example

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "resources": {
      "type": "array",
      "value": [
        {
          "id": "Resource1",
          "type": "Compute",
          "description": "Main compute resource",
          "source": "file1"
        },
        {
          "id": "Resource2",
          "type": "Storage",
          "description": "Storage resource",
          "source": "file2"
        }
      ]
    },
    "ResourceGroup": {
      "type": "string",
      "value": "TestRG"
    },
    "Environment": {
      "type": "string",
      "value": "Production"
    }
  }
}

License

This project is licensed under the MIT License. See the LICENSE file for details.

Third-Party Libraries

This project leverages the following third-party libraries:

• YamlDotNet
  Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014 Antoine Aubry and contributors
  Used for YAML serialization and deserialization. YamlDotNet is distributed under the MIT License. For detailed information, refer to the YamlDotNet License.

• YamlDotNet.System.Text.Json
  Copyright (c) 2022 Ivan Josipovic
  Facilitates type handling for YAML serialization and deserialization, enhancing compatibility with System.Text.Json. This library is also distributed under the MIT License. For more details, see the YamlDotNet.System.Text.Json License.

Contributing

Contributions are welcome! Feel free to submit issues or pull requests on GitHub.