Divorcing from Metalama

A few years ago, while serenading an Israeli prospect with the sweet melodies of PostSharp, they curiously asked if this was like a Catholic marriage — you know, that "til death do us part" kind of commitment to the framework. At the time, we sheepishly scratched our heads, trying to come up with a reassuring answer. Sure, it's possible to remove PostSharp, but you'd have to rewrite all that generated code by hand. And, in the process, you'd be wiping out all those precious time savings you have happily amassed over the years. Talk about a messy breakup with a costly aftermath!

Enter Metalama, the humble spouse of the software world! Unlike that clingy ex-partner, Metalama gracefully accepts when it's time to part ways and makes the breakup process as smooth as possible. With the metalama divorce command, there's no need for a lengthy, handwritten code separation. It's like a considerate partner injecting the generated code right into your source code, preserving your sanity and your time.

Of course, you will no longer enjoy the benefits of Metalama. You'll have to write your boilerplate code by hand again validate your architecture by manual code review over and over again. But hey, it's your choice! If you don't enjoy the relationship, Metalama won't be the one to force you to stay. It understands that sometimes, you just have to go back to the good ol' fashioned way of doing things.

In just a few hours, Metalama will be but a distant memory, allowing you to return to your beloved, plain-Jane Microsoft compiler. So, raise a toast to Metalama, the software that makes digital divorces swift, smooth, and a tiny bit hilarious, while keeping your valuable time intact and demonstrating that not all breakups have to be painful!

And hey, before you take that painful plunge into the sea of software separation, remember that we, the Metalama team, are always here — ready and happy to chat, like a comedic therapist with a cup of virtual coffee, to help you reconsider or navigate those tricky relationship waters!

Step 0. Consider your decision carefully

Despite Metalama's best efforts to make the separation process smooth, it's essential to remember that no divorce is truly painless, even in the world of software.

The metalama divorce command will automatically inject a significant amount of boilerplate code into your source code. Consider the following potential inconveniences:

• You will now have to maintain this boilerplate code manually.
• Metalama does not always generate code that a human would write. Your codebase may look non-idiomatic after the divorce. You can preview what Metalama does with your code using the feature described in Metalama Diff.
• The changes will result in a large commit that may be challenging to merge if your colleagues are concurrently working on other branches of the same repo.
• Returning to Metalama after the divorce can be even more painful because you would need to remove the boilerplate manually, unless you can easily revert the divorce commit.

Step 1. Prepare your code

We recommend formatting your code to your preferred standard using a tool like dotnet format or the Clean Up feature of ReSharper or Rider. This is because the code generated by Metalama will not respect your preferred standard, and you will need to reformat your code after the metalama divorce command has executed.

Ensure all your unit tests are successful.

Step 2. Commit your code

Ensure that your code is committed in its repository. Create a separate branch for the divorce and check out that branch.

Step 3. Build your code with special flags

1. Open a terminal window.

2. Define the following environment variables:

   $env:MetalamaEmitCompilerTransformedFiles="true"
   $env:MetalamaFormatOutput="true"
   

   Note that the syntax differs if you're not using PowerShell. You can also define these properties in Directory.Build.props, but make sure they apply to all projects using Metalama.

3. Rebuild all your projects. Don't miss any! Your build may take longer than usual due to the MetalamaFormatOutput property.

Building the projects with these two properties will write the transformed code files to disk in the transformed directory, located under the obj directory of each project.

Step 4. Execute the divorce command

Install the metalama tool as described in Installing the Metalama Command Line Tool.

Then, execute the following command from the root directory of your repository.

metalama divorce

This command will copy all files under the obj/**/transformed directory back to their original location in the source code.

Step 5. Reformat your code

We suggest you format your code again using the same tool and parameters as in Step 1.

Step 6. Commit

Review the changes in your repository and commit them to your new branch. Do not merge yet, you're not done!

Step 7. Remove any reference to Metalama

At this point, your code base no longer requires processing by the Metalama compiler. If you build the repository now, the standard Microsoft compiler will be used instead. However, your code base still contains references to the Metalama libraries. Removing them can be a tedious process.

Currently, Metalama does not provide a way to automatically remove fabrics and aspect custom attributes from your code. Therefore, we recommend:

• Editing all aspects to turn them into plain custom attributes,
• Removing all fabrics.

PowerShell script

The steps above, except the last one, are summarized in the following script.

# Run git status and capture the output
 $gitStatus = $(git status --porcelain)

 # Check if the repo has uncommitted changes
 if (-not [string]::IsNullOrWhiteSpace($gitStatus)) {
     throw "Uncommitted changes detected. Please commit or stash your changes."
 }

 # Create a new branch
 $currentTimestamp  = Get-Date -Format "yyyyMMdd-HHmmss"
 $branchName = "divorce-$currentTimestamp"
 git checkout -b $branchName

 # Format code
 dotnet format

 # Commit
 git commit -a -m "Formatting the code before Metalama divorce."

 # Enable code formatting for Metalama
$env:MetalamaEmitCompilerTransformedFiles="true"
$env:MetalamaFormatOutput="true"

# Rebuild
dotnet build /t:rebuild

# Write generated code back to the source code
metalama divorce

## Format
dotnet format