1. self-contained interchangeable unit: an independent unit that can be combined with others and easily rearranged, replaced, or interchanged to form different structures or systems

In SharePoint, <Module> is the part of CAML (Collaborative Application Markup Language) that provisions files into the Content Database. It has one permissible child element: <File>. So maybe it could have been more mnemonically named <FileProvisioner> or <AddTheseFilesToTheContentDatabase>. However, it does rearrange an independent unit (a file) to form different structures.

<Module> comes in two flavors: Module Element (Module) and Module Element (Site). They have the same set of attributes, and the same single child element: <File>. The difference is where each is found, and the starting location for the Module's Path attribute. Module Element (Module) is found in a Feature's Elements.xml, and accordingly the Path attribute is relative to {SharePointRoot}\TEMPLATE\FEATURES\FeatureName. Module Element (Site) is found in a Site Definition's Onet.xml, and the Path attribute is relative to {SharePointRoot}\TEMPLATE\SiteTemplates\Site_Definition.

Modules can rename, repurpose, and provision one physical file to many locations

This post will focus on Module Element (Module) - the one found in Feature xml - but the concepts are the same for both flavors. For simplicity, Farm Solution Features will be the target of the initial discussion - it is easier to see where the physical files are when they're on the file system. The essence of a Module Element (Module) is taking a file found in its Feature's folder structure, and provisioning that file into the Content Database, so that it becomes a file in an SPWeb's folder or in an SPWeb's list/library.

Why is a file "provisioned" rather than "copied"? When the Module provisioning process deposits a file into the database, it deposits an SPFile object. When that SPFile is first created (provisioned), it is designated "uncustomized", meaning it works like a pointer to the actual physical file on the Web Front End (WFE) server's file system - the file in the Feature's folder. In Module provisioning, a single physical file can be virtually renamed, provisioned to multiple locations, and properties can be set, or objects added, depending on what kind of file it is. If the file is an aspx page, navigational elements or web parts can be added. If it is a webpart file, properties can be set. Consider this somewhat contrived illustration:

In the illustration above, a Module takes a single web part page (BasicLeftRightZones.aspx) and renames, repurposes, and provisions it to five different locations in a web. This is really awesome for scaling purposes. There's just one physical copy of BasicLeftRightZones.aspx, and if that physical copy is changed, the changes are propagated everywhere. However, often a single file just gets provisioned to a single location, but since this is part of Feature deployment, provisioning might happen many times, on multiple Sites or Webs. What if one of those Sites/Webs needs to alter such a file?

Customized or Uncustomized, that is the question

Imagine that a Feature named "AlphaApp" contains a Module which provisions a file named "Alpha.aspx", and the AlphaApp Feature has been activated on 3,274 sites. In the database, that's 3,274 "uncustomized" SPFile objects which are pointers to the one physical "Alpha.aspx" in the {SharePointRoot}\TEMPLATE\Features\AlphaApp folder. Then on one of those 3,274 sites, the "Management" site, someone uses SharePoint Designer to alter the source of Management's Alpha.aspx. The Management site's Alpha.aspx SPFile is now "customized", and no longer functions like a pointer to the file system; instead, the customized Alpha.aspx source is now actually in the database. The SPFile class has a property, CustomizedPageStatus, which indicates whether the file's status is currently "uncustomized" (and cached), "customized" (and not cached), or "none" (never cached). "Cached" means cached in memory on the WFE server. What's with that caching? It goes hand-in-hand with the customized page status. The SPFile class also has method RevertContentStream() which returns the file to its uncustomized state.

Files can be uncustomized in SharePoint Designer, in code, and through the browser by choosing Site Actions > Site Settings > Reset to Site Definition. This last option lands on the "Reset Page to Site Definition Version" page, where one can select one file to revert, or the entire site. Charmingly, the actual webpage name there is "reghost.aspx", which is a reference to the old SharePoint way of labeling SPFile files as ghosted or unghosted. In SharePoint 2010 terms, ghosted = uncustomized, unghosted = customized.

FROM and TO

If a Module Element (Module) provisions files from a Feature folder to the database, it must have something like a FROM and a TO. Or maybe the <File> element has the FROM and TO. Confusingly, both <Module> and <File> elements have FROM and TO bits.

Modules elements have a bunch of attributes, but the ones primarily involved in the FROM/TO business are these: Url, Path, and SetupPath. Similarly, the File element has attributes Url, Path, and Name. Some of these do double duty, sometimes acting as a FROM, sometimes acting as a TO. What attributes are required? For a Module, the Name attribute is required; for a File, the Url attribute is required. Let's explore some examples, all based on a web whose Url is http://intranet. The simplest Module could look like this:

<?xml version="1.0" encoding="utf-8"?>

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

  <Module Name="Simple">

    <File Url="Sample.aspx" />

  </Module>

</Elements>

In the above example, the File element's Url attribute is both the FROM and the TO. This CAML code says that Sample.aspx is in the Feature's root folder, and will be provisioned to the Web's root folder. After provisioning, one could browse to http://intranet/Sample.aspx. However, this is an uncommon configuration; in fact, one cannot build this in Visual Studio, since it will not allow files to be added to the Feature's root folder. (There are examples of the Url attribute being both FROM and TO and files living in the Feature's root folder in the built-in Features, such as the BasicWebParts Feature.)

Since the Url attribute is required for the File element, it will always function as either the FROM or the TO (or both, as above). In the File element, if the Name attribute is added, Name becomes the TO, thus making Url the FROM. If instead the Path attribute is included, Path becomes the FROM, thus making Url the TO. (See why this is confusing?) For the rest of the code examples, just the Module and File elements will be shown. Here's an example using just Url and Name:

  <!-- FROM: Url   TO: Name-->

  <Module Name="Simple">

    <File Url="Sample.aspx" Name="Alice.aspx" />

  </Module>

Now one could browse to http://intranet/Alice.aspx. The Sample.aspx file has been renamed Alice.aspx and placed in the web's root folder.

How about this:

  <!-- FROM: Url   TO: Name-->

  <Module Name="Simple">

    <File Url="Sample.aspx" Name="Books/Alice.aspx" />

  </Module>

Now one could browse to http://intranet/Books/Alice.aspx - the Sample.aspx file has been renamed Alice.aspx, and a folder (Books) has been automatically provisioned to contain it. How about this:

  <!-- FROM: Path   TO: Url-->

  <Module Name="Simple">

    <File Url="Books/Alice.aspx" Path="BookPages\Sample.aspx" />

  </Module>

One could still browse to http://intranet/Books/Alice.aspx, but the original file is now found in the BookPages folder under the Feature folder. This is typically what one would see in Visual Studio, except that it would default the Url attribute to BookPages/Sample.aspx. What if one tried using Path, Name, and Url in the same File element?

  <Module Name="BookPages">

    <!-- FROM: Path   TO: Name  (Url is ignored) -->

    <File Path="BookPages\Sample.aspx"

          Url="Books/Alice.aspx"

          Name="Books/Fiction/Alice.aspx"/>

  </Module>

Name wins! This will provision Alice.aspx and two nested folders, so that one can browse to http://intranet/Books/Fiction/Alice.aspx. The Url attribute is ignored - but remember it cannot be removed, it is required, and it cannot be empty. Clearly this is not an optimal situation; a better practice would be choosing Url+Name attributes or Url+Path attributes, but not all three.

A couple of other attributes for the File element deserve special attention. Contemplate the attribute IgnoreIfAlreadyExists. Sounds like that means one can overwrite an already provisioned file, but nope, that's wrong. IgnoreIfAlreadyExists is Boolean, and if set to True, the Module will not throw an exception if it encounters an existing file. If IgnoreIfAlreadyExists is not present, or is set to False, and the Module encounters an existing file, it will throw an exception. So, if you'd rather not be notified that the Module failed to provision a file because the file was already there, set IgnoreIfAlreadyExists="True". Maybe it should be renamed DontThrowExceptionIfFileAlreadyExists.

  <Module Name="BookPages">

    <!-- FROM: Path   TO: Name  (Url is ignored) -->

    <File Path="BookPages\Sample.aspx"

          Url="."

          Name="Books/Fiction/Alice.aspx"

          IgnoreIfAlreadyExists="TRUE">

    </File>

  </Module>

Why would the file already be there? Because Modules do not clean up behind themselves; they provision when the Feature is activated, but do not un-provision when it deactivates. Typically the FeatureDeactivating method is used to clean up files left lying around by Modules. Then the coast is clear for a new provisioning. Of course, if the business user has made customizations through the browser, those will be lost - so there may be times when that mysterious IgnoreIfAlreadyExists="True" attribute is useful.

Visual Studio quietly takes care of deployment conflicts (like the file already exists) by default. Watch the Output window when deploying a Module Feature the second time, and you'll see something like "Found 1 deployment conflict(s).  Resolving conflicts ...Deleted file 'http://intranet/Books/Fiction/Alice.aspx' from server." This is great for development, but be aware that in production, re-activating a Feature with a Module will throw an exception if there's been no cleanup of those files orphaned by the Module. This Visual Studio behavior can be controlled by the Deployment Resolution Conflict property on a Module's folder. In Solution Explorer, select the Module folder, then peek in the Properties window.

GhostableInLibrary and Ghostable

Let's look at provisioning to a List - a specialized List known as a Document Library in this case:

  <Module Name="BookPages" List="101" Url="Docs">

    <!-- FROM: Path   TO: Url+Url -->

    <File Path="BookPages\Sample.aspx"

          Url="Alice.aspx"

          Type="GhostableInLibrary"/>

  </Module>

The File element has sprouted another attribute, Type="GhostableInLibrary". If this is left off, the file will not provision to the Library. Remember the old SharePoint terms "ghosted" and "unghosted"? Yep, this hearkens back to those older terms, and specifies that the file provisions to a Library, and is cached. The List attribute in the Module element is not required, but it can help alert one to a missing library. Without it, SharePoint will merrily create a folder if no such library exists at the Module's Url. With it, SharePoint will throw an exception if there's no library. (A spurious folder when one expected a Library can be hard to troubleshoot.) The number 101 in List="101" is the List Template Type. For a listing of List Template Types, see SPListTemplateType Enumeration.

The final Url is now a concatenation of the Module's Url attribute (which is the List's Url) and the File's Url attribute (which is the final name of the file), so one can browse to http://intranet/Docs/Alice.aspx, and see the file in the Library Docs. The Module element can also have a Path attribute, which prefixes any Path attribute in the File element.

Take a look at this variation which uses the Path attribute in the Module element to provision a folder in the Library, and stuffs Alice.aspx in it, resulting in a Url of http://intranet/Docs/Books/Alice.aspx:

  <Module Name="BookPages" List="101" Url="Docs/Books" Path="BookPages">

    <!-- FROM: Path+Path   TO: Url+Url -->

    <File Path="Sample.aspx"

          Url="Alice.aspx"

          Type="GhostableInLibrary"/>  

  </Module>

But what about the Type=Ghostable attribute?

<Module Name="BookPages" List="101" Url="Docs">

    <!-- FROM: Path   TO: Url+Url -->

    <File Path="BookPages\Sample.aspx"

          Url="Alice.aspx"

          Type="Ghostable"/>

  </Module>

Switching to Type="Ghostable" creates a "Docs" folder at http://intranet/Docs, with Alice.aspx inside it, and now again one can browse to http://intranet/Docs/Alice.aspx. Since there's already a Library at http://intranet/Docs, this could be seriously confusing.

SetupPath, Sandboxed Solutions, and the Visual Studio view

There's one more Module attribute to mention: SetupPath. Pick Path OR SetupPath, but not both. SetupPath is the physical path to a folder which is relative to {SharePointRoot}\TEMPLATE, so it's a way to reference files in folders there or below. If you inadvertently include both, SetupPath will win. Want to grab Default.aspx from the Team Site definition and add it to the Docs Library as Nathan.aspx?

  <Module Name="BookPages" List="101" Url="Docs" SetupPath="SiteTemplates/STS">

    <!-- FROM: SetupPath+Path   TO: Url+Url -->

    <File Path="Default.aspx"

          Url="Nathan.aspx"

          Type="GhostableInLibrary"/>

  </Module>