This attribute doesn't quite work the way I expected it to, or the way I have seen it described in other places on the web. (The documentation is not as clear as it should be. I really wish it did work the way described in Chris's great post!)
From the official documentation (http://msdn2.microsoft.com/en-us/library/ms459213.aspx) we find that it is designed to:
Optional Boolean. TRUE to provision the view even if the file already exists at the specified URL; otherwise, FALSE.
To fully understand how this attribute worked I set up the following test:
- Created a Feature (ReplaceTest1) which simply provisioned a file (test.aspx) into a team sites /_catalogs/masterpage folder. The file simply contained "11111111".
- I then tested this and confirmed that it worked correctly, I saw "11111111" when accessing the page.
- I then created another feature (ReplaceTest2) based on ReplaceTest1, except with:
- A new FeatureID
- I added the IgnoreIfAlreadyExists parameter, and set it to TRUE
- Modified the test.aspx file to contain "22222222" instead.
- I then activated this feature, and in doing so found that it didn't actually replace the existing test.aspx file. In the browser I still saw "11111111". I didn't expect this.
- I then decided to change ReplaceTest2 so that IgnoreIfAlreadyExists was equal to FALSE
- I then repeated the tests and found that this time, when activating ReplaceTest2, I received an error telling me that the file already existed. I did expect this.
So, in summary, it appears this attribute actually does exactly what it says (even if it really could have said it clearer), it ignores the provisioning of the file if a file with the same name already exists. At this point I have to wonder just how useful such an attribute really is!
Anyway, I'm going to return to investigating the easiest way to replace an existing file via a feature, but if anyone out there has had a different experience then I would love to hear about it.