When developing with SharePoint it can be frustrating when changes are deployed and activated in a Solution package and the changes do not appear in the browser. This can include CSS, image, and JavaScript files and also Master Page and Page Layout changes. This post outlines some of the mechanisms to be aware of when planning your solution update strategies and troubleshooting "missing" content changes.
The decision where to deploy "visual" files that are cacheable in the browser such as CSS, image, and JavaScript files depends on who will own the content once the system is live. If the content needs to be owned and maintained by the content administrators, then deploy it to the content database (somewhere under Style Library). However be aware that once your content administrators modify the content, future deployments of your solution will have no impact on the file in the content database - this is true even if you retract and re-deploy your solution (although there is a workaround to reset to the site definition described below). If the content needs to be changed in the future by the development team, then deploy the files to a solution-specific folder under the 12 hive LAYOUTS folder.
Master Pages and Page Layouts must be deployed to the content database. This opens up the possibility that your content administrators can modify these files. It's also common during development for a creative or development resource to work with the Master and Page Layouts in SharePoint Designer and then deploy them later with a solution. If a Master Page or Page Layout is modified from the content database, then future updates to that file when you re-deploy your solution will have no effect. You will be left wondering, I know I deleted and re-installed the solution, why aren't my changes showing up? You can clear your browser cache several times, and restart SharePoint, and still the changes will not show up.
The reason for this is as with images and CSS files deployed to the content database, once Master Pages and Page Layouts have been customized then SharePoint does not allow solutions to overwrite them. Depending who you talk to or what article you read, or how late you end up working when vexed by this problem, you might consider this a feature or a bug. However SharePoint does provide a way to reset the content database to the version you have deployed, with the caveat that all history is erased. The way to do this is go into Site Settings > Modify All Site Settings and under the Look and Feel column click Reset to site definition:
Next enter the complete path to the file you want to reset. Click here for more of the theory and details on resetting customization changes. This technique works for any file deployed to the content database - image, CSS, JavaScript, Master Page, Page Layout, etc. However it also erases all version history, so please exercise this power responsibly.
SharePoint provides a caching architecture which helps to minimize the overhead of retrieving dynamic content from the databases it manages and to provide other performance improvements. Click here for a useful overview of the caching architecture. You can manage and clear the caches in Site Settings > All Site Settings by clicking the indicated links below:
Recall from earlier my recommendation that CSS, image, and JavaScript files that will be deployed as part of solution and need to be updated by developers should be deployed to a solution-specific layouts folder under the 12 hive. This prevents the files from becoming customized. A second benefit is that by deploying to the file system under the layouts folder, you can now set caching directives in IIS to tell browsers how frequently to check for new versions of the content.
Here's something you need to know that you won't see frequently documented but which can have enormous impact on your changes not making it down to the browser: By default SharePoint sets a far futures header of 365 days on all files deployed to the LAYOUTS and CONTROLTEMPLATES folders under the 12 hive. This means that if you deploy an image, CSS, JavaScript, or ASPX application page to any of these folders, the browser will not check back for 1 year to see if the content has changed. Each user would have to clear their cache or explicitly reload the page to see the changes. Note that this default is very different then what we ASP.NET developers are used to - normally when you create a site in IIS there are no far futures headers set.
Fortunately there is an easy way to prevent your content from being cached and then not being reloaded when you later deploy a new version of your solution. You can turn off content expiration for your solution-specific folder under the LAYOUTS folder, and likewise for CONTROLTEMPLATES if you are deploying any browser-loadable files there (ASCX files are not loaded by the browser).
Right-click the solution-specific folder under _layouts and click the Http Headers tab. Note that content is set to not expire for 365 days by default:
Uncheck "Enable content expiration" and Apply the changes:
Note that you and your users will need to clear their browser cache to reload the content the first time. After that the content will be refreshed when changed in the web browser. This is why it's so important if possible to plan this out before your site is launched - otherwise if you have deployed browser-loadable files then the browsers are all sitting there thinking the content doesn't expire for 365 days after they first accessed your site. If the situation you are in is your site has already been launched, then changing the names of the files and updating your links is one way you can reset the clock.
Finally, a great tool to help in resolving caching and content updates is the freely available Fiddler Web Debugger, an easy to install proxy which can be used to trace all HTTP and HTTPS traffic. The Firefox Firebug and YSlow add-ons are useful in helping to track down how many files are being loaded and what the key headers (like Expires) are set to.