Maintaining and Debugging Site Definitions
| Although we will talk more about site definitions in upcoming chapters, now is a good time to take a step back and give some general insight into maintaining and debugging them. As you work with site definitions, you will inevitably run across technology restrictions, business restrictions, and maintenance and debugging issues. Over the next few pages, we address some of the more common site definition issues and their resolutions. Overcoming Site Definition LimitationsAlthough site definitions have a customization option for just about everything, they have limitations. Those shortcomings include: (1) themes cannot be specified, (2) security settings cannot be set explicitly, and (3) limitations exist in prepopulating document library content. However, all these shortcomings can be overcome either by leveraging other site definition customization or using the SharePoint API shortly after site creation to overcome these issues programmatically. For instance, the Artic theme can be applied programmatically to a newly created site as part of a custom provisioning process, or a custom CSS that is functionally equivalent to the Artic theme can be applied through AlternateCSS. In the case of restricting access to a document library, a custom application can be run after the site is created to initialize a set of permissions, or the list could be marked as a private list or hidden. Finally, content could be uploaded to a newly created site with an application that uses WebDAV, or it could be added through the site definition in a similar manner to the way that hidden views and forms are added to a library. In the latter case, the content would not appear as an element in the document library but rather would exist just as Forms/ALLITEMS.ASPX does. In all these cases and the cases that you encounter, there is always a way around the limitation. In general, try to think of a creative way to implement the functionality within the site definition first and a programmatic solution second. Restricting Functionality in the EnterpriseCustom templates provide an easy way for business users to create their own templates. Although sites based on custom templates are slightly slower than those based on site definition templates and provide less functionality, they provide an enormous opportunity for empowering business users. Many large companies wrestle with allowing or disallowing customizations through custom templates or other means. The ROI on empowerment is always countered by its costs, which include administration, maintenance, user support, and additional server resource consumption. In general, many enterprises selectively lock down user functionality on universal SharePoint offerings and prefer to open up functionality on specialty server farms. This approach helps to minimize costs so that only a few server farms bear increased costs of operation. Restricting functionality in SharePoint can take many forms. The three primary vehicles include:
Site Definition MaintenanceAfter the template is deployed, additional changes should not be made. Instead, the template should be versioned, and a new updated template should run side-by-side with the old template. However, there can be cases where changes must be made to an existing site definition template. Potential scenarios include adding static links to the site's home page or changes to a document library in response to an edict handed down from on high. In cases such as these, we feel it is important to highlight that it can be doneaccompanied by the strong recommendation for versioned templates. Although it is technically possible to upgrade all aspects of a deployed site definition, it is virtually impossible from a practical standpoint. Deployed site definitions rely on both physical files (the site definition files) and data within the database. This data includes not only content formatted in accordance with the site definition's various XML configurations, but also deltas from the views (additional views, modified existing views, and so on) and schemas (modified existing columns, new columns, deleted columns, and so on). Thus, modifications to deployed site definitions can require changing the underlying data. The most difficult changes to deployed site definition templates are the ones that require changing the underlying data in the database. In the first scenario, the links need to be added to the DEFAULT.ASPX page. This would require simply making changes to that ASPX page, and it represents a very easy change with no database implications. The scenario of extending a Document Library schema is a bit more complicated. Although it would be possible to make changes in placemodify the document library's schema and then run a SQL script on the database to update it with regard to the new schemaa much simpler alternative exists. Trying to update an existing list definition's SCHEMA.XML and then develop and run a SQL script to update a production database is not fun or easy. The alternative is to hide the creation of the old document library and then create a new document library with the extended schema. This technique would not preclude the use of the existing old document libraries. Furthermore, only the new document libraries could be created. If you are using a custom assembly with your versioned site definition templates, an updated custom assembly might need to be used with the new site definition template. Most likely you cannot simply upgrade the assembly in place because its new functionality might not be compatible with the older site definition template. Although there are many ways to do this task, it is preferable to run multiple assemblies that share the same class name but differ by version. As shown in Listing 2.30, you can use dependentAssembly within SharePoint's WEB.CONFIG to accomplish this job. Listing 2.30. Example Use of dependentAssembly in WEB.CONFIG
DebuggingMistakes happen. .NET provides great debugging functionality for errors within ASPX pages and web parts. Unfortunately, this rich debugging support does not necessarily translate to site definitions. When an error exists in a site definition, you will usually receive a very general error message that does not give you insight into what was specifically wrong. This generic error is shown in Figure 2.25. The purpose of this section's discussion is to give some insight into where the problem might be happening, given the terse clues from SharePoint. Figure 2.25. Error in site definition. When applying a site definition template to a newly created site, a problem in WEBTEMP Figure 2.26. Error in site definition because the template was invalid. Figure 2.27. Error in site definition because a file was not found. Tracking Down the ProblemWhen you receive one of the errors shown in Figure 2.25, Figure 2.26, and Figure 2.27, click the Home link to examine the home page. Examining the home page will help direct us to the problem. If you are again prompted to apply a template, then the problem is with the site definition's WEBTEMP If your site's home page looks partially deployed, similar to Figure 2.28, then the problem is most likely with ONET.XML. Because you could deploy part of the template, your WEBTEMP Figure 2.28. Partially deployed site definition without top navigation links. If you receive a 404 NOT FOUND error, then the problem could be in WEBTEMP Keep in mind that problems in SCHEMA.XML might not necessarily trigger one of these errors. These errors are only visible when viewing the affected page in the list. Such a failure is shown in Figure 2.29. Figure 2.29. SCHEMA.XML error. After narrowing down the error's possible locations and triple checking that the problem is not with WEBTEMP.XML, you might still be at a loss. In those situations, I find it best to selectively remove List and Module elements from the selected site definition template Configuration in ONET.XML. After making the changes, be sure to execute an IISReset.EXE and then create the site anew. In fact, it is always safest to create a new site when trying to work through an error. It is tempting to only create a new instance of a list within an existing site when trying to debug a problem with a list definition. Although this method can be quicker than creating a new site and then going through the process of checking the changes, there are cases when your changes do not appear to fix the problem in an existing broken site. Thus, you could be spinning your wheels and be thoroughly frustrated even though the site definition template problem was resolved but didn't appear so because the underlying site instance was broken. |
.XML, ONET.XML, or the list definitions SCHEMA.XML could trigger the generic errors shown in Figure 2.25, Figure 2.26, and Figure 2.27.
EAN: 2147483647
Pages: 64