I have just been through two weeks of tough debugging and lots of code rewriting to get rid of all of the uses of MetadataMutator in the CCI codebase. The warnings about MetadataMutator being difficult to use correctly are very accurate indeed. A major
check in is coming soon. Some breaking changes as well.
The idea is to first make a copy of your assembly using MetadataCopier. Now that copy is fully mutable as well as self consistent and traversable. You just call MetadataCopier.
As for the mutator bit, you now subclass MutatingVisitor instead of MetadataMutator and provide overrides for the Mutate methods instead of the Visit methods.
Incidently, if you are going to make point mutations, such as adding in a field or a method, you may as well just use an ordinary BaseTraverser and cast down the nodes of interest to the mutable nodes they really are (after MetadataCopier has done its work).
This can be more efficient than using MutatingVisitor since you are just traversing the tree rather than systematically rewriting it.
I am less than thrilled with the confusing API inconsistencies and concept overloading between visitors, traversers and mutators and I'll be looking at some API changes to make things a bit more intuitive in the next few weeks.