PostAction for modifying the deployment.template.json file in IoT Edge solutions

[fgheysels]

Is your feature request related to a problem? Please describe.

I'm creating a project template for a custom IoT Edge module. When adding an iotedge module to an IoT Edge solution, you need to update the deployment.template.json file that is part of the solution to include that new module into the deployment.
It would be nice if there's a custom 'PostAction' which can do these modifications for you, as I currently don't see any way to do this myself.

As I read that the VS.NET extensions is in maintenance mode, and the CLI way will be the preferred way to create IoT Edge solutions / projects, this should be beneficial for Microsoft too ?

Describe the solution you'd like.

It would be nice if there would exist a PostAction that adds a new entry to the modules section of the deployment.template.json file that exists in an IoT Edge project.
It would be helpfull if the developer could also specify the filename (or filenames) of this json file, as it is very much possible that an IoT Edge solution has multiple different deployment templates.

That new entry should look like this:

"IotEdgeModule1": {
            "version": "1.0.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "settings": {
              "image": "${MODULEDIR<../IotEdgeModule1>}",
              "createOptions": {}
            }
          }

Where IoTEdgeModule1 is the name of the new module. This could be the sourceName property of the template.

If this is too specific for a post-action, you could instead provide a post-action that is more generic. A post-action that allows the developer to add a JSON-object / subproperty to a specific property in a specific JSON file could maybe also do the job.

Additional context

No response

[vlada-shubina]

Related issues:

• Update PostAction with symbol parameters to cmd file arguments #1600
• Add properties/items to project file when generating template #5812

[vlada-shubina]

@fgheysels

Thank you for suggesting.
At the moment unfortunately it doesn't meet our priority bar, so this might be a good opportunity to contribute and create such a post action.

To everyone, if you feel that this feature (or modifying JSON files in post action) is useful for you, please let us know your use case in comments or simply react to the issue. This helps us prioritize the relevant issues. Thank you.

[fgheysels]

@vlada-shubina
Is there any documentation available on how to contribute for creating new PostActions ?

[vlada-shubina]

Unfortunately, we don't have any specific guideline for post actions specifically, but I can share the high-level steps here:

• post actions for dotnet CLI (dotnet new) are located in dotnet/sdk repo. Generic information on how to build and test the repo is given here.
• to implement new post action you need to implement IPostActionProcessor interface or inherit from PostActionProcessorBase
• existing post actions implementations: https://github.com/dotnet/sdk/tree/main/src/Cli/Microsoft.TemplateEngine.Cli/PostActionProcessors and https://github.com/dotnet/sdk/tree/main/src/Cli/dotnet/commands/dotnet-new/PostActions
• the main task is to implement Process method that does post action. You get the following details: IEngineEnvironmentSettings containing template engine settings, IPostAction containing information about post action (conditions are already evaluated at that point), including custom arguments, ICreationEffects and ICreationResult that contain primary outputs and files created by template execution.
• once the post action is implemented, it should be initialized here
• unit tests for post actions are here
• end to end tests for post actions are here
• test resources (templates used in tests) are here
• consider updating documentation for post actions here and JSON schema for configuration

Please feel free to reach out if you need more information.

Thank you

[fgheysels]

Thanks for the information @vlada-shubina
I've followed the info that is described here, but most of the projects cannot be loaded by VS.NET.
That's strange as I suspect that by running the build.ps1 and afterwards the sdk-build-env.ps1 script, I would assume that I have a 'self build' .NET 8 sdk ?

Next to that, if I succeed in creating such a post-action, will this only become available with .NET 8 ?

[vlada-shubina]

Thanks for the information @vlada-shubina

I've followed the info that is described here, but most of the projects cannot be loaded by VS.NET.

After some investigation, this is because the SdkTargetFramework variable is set to .NET 8, but obviously, I do not have that SDK. :)

I could change the Directory.Build.props or targets file to target .NET 6 or 7 instead, but I don't think that this is the intention.

Next to that, if I succeed in creating such a post-action, will this only become available with .NET 8 ?

It is possible to download latest daily version of .NET from https://aka.ms/dotnet/8.0.1xx/daily/dotnet-sdk-win-x64.exe (list of all the packages available here: https://github.com/dotnet/installer). If you are using VS, you would probably need to use latest preview that supports .NET 8.

Alternatively, you can use release/7.0.2xx (or release/7.0.3xx once available) - they are built using .NET 7, and thats even more preferable.

Depending on the when the PR will be ready, it might go with .NET SDK 7.0.200 or 7.0.300. The code freeze for 7.0.200 is in two weeks.

[fgheysels]

I've been working on this for a while now, and I think I made some good progress.
However, I've noticed that the template engine is not replacing references to the sourceName in a postaction.

Suppose I have a template that looks like this (only relevant parts included):

{
  "name": "SomeTemplate",
  "identity": "SomeTemplate",
  "shortName": "SomeTemplate",
  "sourceName": "MyProject",
  "primaryOutputs": [
    {
      "path": "MyProject.csproj"
    }
  ],
  "postActions": [
    {
      "description": "Modify JSON file",
      "args": {
        "jsonFileName": "deployment.template.json",
        "parentPropertyPath": "modulesContent:$edgeAgent:properties.desired:modules",
        "newJsonPropertyName": "MyProject",
        "newJsonPropertyValue": "{\"image\":\"${MODULEDIR<../MyProject>}\"}"
      }
    }
  ]
}

As can be seen, the 'arguments' of the post-action contain some strings containing MyProject which is the sourceName that is configured in the template.
I would have expected that these strings would be replaced by the eventual project-name as well, but that is not the case. Of course, the template.json file is not part of the 'project template' itself, so I can understand that this is not happening.
However, inside the post-action, I also have no knowledge of the sourceName nor the string-value that is used to replace the sourceName. Maybe I'm missing something, but none of the parameters of the ProcessInternal method contain this information.

Is there any way to achieve this ?

edit: I've currently 'worked around' this by making use of the filechanges in the CreationEffects. It's a hacky solution imo, but I cannot come up with something better.

[fgheysels]

I have created a (draft) Pull Request for this (dotnet/sdk#29880) .
The PR contains unit- and end-to-end tests. Documentation still needs to be provided, but I think it would be good to see if this change will be acceptable before doing some work on documentation.

[maridematte]

@fgheysels, just to make sure that I understand the scenario that you are proposing. The post action will add properties to a json file, and that post action can / will be used multiple times depending on the number of properties that you want to add to that specific json file.

As for the file name, during post-actions we do not have ready access to the final name of the project files. You can read a bit more here on how we currently handle file names during that process. But, I think using CreationEffects to get the name should be ok, since we do not have an easier solution right now.

[fgheysels]

Hi @maridematte
That's indeed correct. The post-action can add a property to a json file. If multiple properties need to be added, the post-action needs to be called multiple times.

[vlada-shubina]

As can be seen, the 'arguments' of the post-action contain some strings containing MyProject which is the sourceName that is configured in the template. I would have expected that these strings would be replaced by the eventual project-name as well, but that is not the case. Of course, the template.json file is not part of the 'project template' itself, so I can understand that this is not happening. However, inside the post-action, I also have no knowledge of the sourceName nor the string-value that is used to replace the sourceName. Maybe I'm missing something, but none of the parameters of the ProcessInternal method contain this information.

Is there any way to achieve this ?

Unfortunately, he args in post actions won't be auto-replaced. Let me check the PR, thanks a lot for contributing.

[vlada-shubina]

This was fixed in dotnet/sdk#29880, @fgheysels contributed to create post action which covers the scenario.

The example is here: https://github.com/dotnet/sdk/tree/main/src/Assets/TestPackages/dotnet-new/test_templates/PostActions/AddJsonProperty/WithSourceNameChangeInJson

The documentation for new post action is here: https://github.com/dotnet/templating/wiki/Post-Action-Registry#add-a-property-to-an-existing-json-file