The SI SharePoint Blog

Files that have been added to SharePoint can be either customized or uncustomized.  Customized means the data lives in the database.  Uncustomized means the entry in the database just points to a location on the disk.  When you change an uncustomized file on a particular site, for instance using SharePoint Designer, it becomes customized, and is moved into the database.

(Previously the terms unghosted and ghosted were used instead of customized and uncustomized.  This was confusing, and you should forget them right away.)

When files are uncustomized, multiple sites may be using the same copy of the file, so you can change it in one place, without having to update every single instance of it in different sites.  If the files are ASPX pages or master pages, there’s another advantage to having them uncustomized: Customized pages have a lot of restrictions.  For instance,  you can’t have inline code or use sessions without adding an exception for your page in the PageParserPaths section of web.config.   The reason is that, otherwise, users of a site could just upload some code and have it executed, which would be a gaping security hole.

Normally you add uncustomized pages through features, using the File element.  But there’s a drawback: If the page exists already, for instance because you’re trying to replace a standard page like default.aspx, there appears to be no way to overwrite the existing file.  The documentation implies that you can do this with the IgnoreIfAlreadyExists attribute, but that’s not actually the case.  IgnoreIfAlreadyExists just determines whether SharePoint should let you know (by failing to activate the feature) that it couldn’t overwrite the existing file.

The only way to overwrite a file as part of a feature activation is to do it programmatically, in the feature receiver’s FeatureActivated event, (and/or delete the file in FeatureDeactivated).  Here’s a good description of how to add a file by parsing the feature definition and adding the SPFile objects in code.  But this example won’t work if you want to add an uncustomized file.

There actually seems to be no way to create an uncustomized file through the SharePoint object model.  There is a method called AddGhosted in the internal SPRequest class, but using SPRequest to bypass the public API leaves your installation in an unsupported state, which is a Bad Idea.

So the only way to add an uncustomized file is with the File element in the feature definition.  And the only way to overwrite an existing file is with code.  How then can we add an uncustomized file and overwrite an existing file at the same time?

Easy: By adding the file with a different name, then use code to move it and replace the original file.

In the feature:

<File Path="Pages\defaultv2.aspx" Url="defaultv2.aspx"/>

And in the FeatureActivated event of the feature receiver:

SPFile sourceFile = site.RootWeb.GetFile("defaultv2.aspx");
sourceFile.MoveTo("default.aspx", true);

Now default.aspx will be read from your location instead of the old one.

The best solution is obviously not to overwrite files that are part of the standard site template at all.  In this example, we could have instead changed the WelcomePage of the site to defaultv2.aspx, like this:

SPFolder rootFolder = site.RootWeb.RootFolder;
rootFolder.WelcomePage = "defaultv2.aspx";
rootFolder.Update();

But there may be circumstances where you want to keep the original URL, for instance if users may have already bookmarked it.  Then you need to do it this way.