Metalama//Conceptual documentation/Divorcing
Open sandboxFocus

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 important to remember that no divorce is truly painless, even in the world of software.

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

  • You will now have to maintain this boilerplate code by hand.
  • Metalama does not always generate code a human would write. Your codebase may look non-idiomatic after divorce. You can preview what Metalama does with your code using the feature described in Metalama Diff.
  • The changes will consist of a large commit that may be difficult to merge if your colleagues are simultaneously working on other branches of the same repo.
  • Going back to Metalama after divorce can be even more painful than divorce because you would need to remove the boilerplate by hand, except if you are still in a situation where you can easily revert the divorce commit.

Step 1. Prepare your code

We suggest that you format your code to your preferred standard using a tool like dotnet format or the Clean Up feature of Resharper or Rider. The reason is that the code generated by Metalama will not respect your favorite standard, and you will have to reformat your code after the metalama divorce command does its job.

Make sure all your unit tests are green.

Step 2. Commit your code

Make sure that your code is committed in its repo. Create a different 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"
    

    The syntax is different if you are not using PowerShell. Note that you can also define these properties in Directory.Build.props, but you need to make sure that these will apply to all projects using Metalama.

  3. Rebuild all your projects. Make sure you forget none! Your build may take longer than usual because of the MetalamaFormatOutput property.

The effect of building the projects with these two properties is to write the transformed code files to disk in the transformed that you can find 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 repo and commit them to your new branch. Do not merge yet, you are not done!

Step 7. Remove any reference to Metalama

So far, your code base no longer needs to be processed by the Metalama compiler. If you build the repo at this point indeed, the plain Microsoft compiler will be used instead. However, your code base still contains references to the Metalama libraries. Removing them can be a tedious process.

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

  • edit all aspects to turn them into plain custom attributes,
  • remove all fabrics.