Archives
-
Windows Installer Cleanup utility
This is a kind of “post to self”. I always forget the name of this great utility that helps you cleanup broken installs, like stuff still depending on .Net Framework beta 2 while you uninstalled it and already installed the RTM version…
So here is the link: http://support.microsoft.com/default.aspx?scid=kb;en-us;290301
-
Usage Event Logging in Windows SharePoint Services - Annotated
A great article on Event Logging in Windows SharePoint Service appeared in july 2004 on MSDN on how to parse the log files that Windows SharePoint Services produces when logging is enabled. The article describes the format of these log files and provides a sample that demonstrates some of the basics for creating a tool that parses the files to extract information about site usage.
This blog post provides more detailed information on the binary log format. This information is especially useful if you want to provide a managed version in for example C# of the log file parser.
Applies to: Microsoft Windows SharePoint Services 2.0, Microsoft SharePoint Portal Server 2003
Exact binary format (see also the referenced article for more info on the fields):
Field
Bytes
Details
pPrev
4 (ABCD)
Value=A|(B<<8)|(C<<16)|(D<<24)
bitFlags
1
-
-
1
Padding to get to WORD boundary
cbEntry
2 (AB)
Value= A|(B<<8)
cbSiteUrl
2 (AB)
Value= A|(B<<8)
cbWeb
2 (AB)
Value= A|(B<<8)
cbDoc
2 (AB)
Value= A|(B<<8)
padding2
2
Padding to get to DWORD boundary
cBytes
4 (ABCD)
Value=A|(B<<8)|(C<<16)|(D<<24)
httpStatus
2 (AB)
Value= A|(B<<8)
cbUser
2 (AB)
Value= A|(B<<8)
cbQS
2 (AB)
Value= A|(B<<8)
cbRef
2 (AB)
Value= A|(B<<8)
cbUAS
2 (AB)
Value= A|(B<<8)
padding3
2
Padding to get to DWORD boundary
Reserved
4
-
-
1
\r
-
1
\n
SiteGuid
36
ASCII string
-
1
0 (delimits string in C++)
Time
8
ASCII string (HH:MM:SS)
-
1
0 (delimits string in C++)
SiteUrl
cbSiteUrl
ASCII string
-
1
0 (delimits string in C++)
WebUrl
cbWebUrl
ASCII string
-
1
0 (delimits string in C++)
DocName
cbDoc
ASCII string
-
1
0 (delimits string in C++)
UserName
cbUser
ASCII string
-
1
0 (delimits string in C++)
QueryString
cbQS
ASCII string
-
1
0 (delimits string in C++)
ReferrerUrl
cbRef
ASCII string
-
1
0 (delimits string in C++)
UserAgent
cbUAS
ASCII string
-
1
0 (delimits string in C++)
-
Macaw Discussion Board on Quick Launch bar
If you create an instance of a list you get the question: “Display this XXX on the Quick Launch bar?”. If you select “Yes” a link to the list is displayed in the quick launch bar of your site. The Macaw Disucussion Board has an issue that even if you select “Yes”, it does not appear on the quick launch bar.
If you go to “Modify settings and columns” of a Macaw Discussion Board list and then select “Change general settings”, you can again answer the question “Display on the Quick Launch bar?”. If you answer this question with “Yes” the link to the Discussion Board becomes available on the quick launch bar.
This same procedure is needed for tools that utilize this setting for displaying lists in their navigation. A good example is the Advis Site Navigator that only displays lists with this setting set to true.
-
MacawSharePointSkinner 1.0.0.1 released
Welcome to the MacawSharePointSkinner. MacawSharePointSkinner is a tool designed to enable non-intrusive modifications to the visual and functional design of SharePoint. The tool can be used for both Windows SharePoint Services 2.0 and for Microsoft Office SharePoint Portal Server 2003. Actually, it can be used for any web site utilizing the ASP.NET technology. Download at
http://www.gotdotnet.com/Workspaces/Workspace.aspx?id=3ed68681-ae28-4d33-8c36-403e6af7fa11UPDATE: can now be found at http://www.codeplex.com/SharePointSkinner.One of the major issues that we encounter in the implementation of SharePoint within organizations is that organizations want modifications to the visual and functional design that are almost impossible to implement without a major overhaul of the standard files and templates provided with SharePoint. SharePoint is constructed as a kind of standard product that is best used out of the box. Some design can be applied by specifying themes (for team sites) or by modifying CSS stylesheets (for the portal). The possibilities here are limited however, and changes to the actual HTML that is rendered results in changes to hundreds of the standard files.
When implementing customer requested visual modifications, one of the big problems that we encountered in making extensive modifications to the files and templates delivered with SharePoint was that the rendering of the same HTML is implemented differently by different pages. Some pages contain the actual HTML that is outputted and can be easily modified. Other pages contain server controls that do the rendering of the same HTML. These pages are almost impossible to modify. Another problem is that modifications must often be made to hundreds of pages.
The approach that MacawSharePointSkinner takes is two-fold:
Text Replacements – MacawSharePointSkinner lets SharePoint render the final HTML, and just before this HTML is sent to the browser MacawSharePointSkinner makes the needed modifications to this HTML. This is done in such a way that no modifications are needed to the internal files of SharePoint, so it is non-intrusive. Another advantage is that it will survive service packs (although the output HTML may change in a service pack!) and template modifications.
Url Redirections – MacawSharePointSkinner can translate requested url’s into other url’s. This allows you to redirect standard SharePoint url’s to your own url’s.
MacawSharePointSkinner is implemented as an HttpModule that provides functionality for url replacements and powerful replacements in the HTML output rendered by SharePoint.
I will not describe the inner workings of an HttpModule, for more information have a look at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconhttpmodules.asp.
1 How to install MacawSharePointSkinner
1.1 Introduction
MacawSharePointSkinner is an HttpModule. HttpModules are configured in the web.config of your ASP.NET web site. SharePoint is an ASP.NET web site. The required DLL is installed in the Global Assembly Cache (GAC).
1.2 Procedure
Follow the steps below for installation:
Step
Action
1
Deploy the DLL Macaw.SharePoint.Skinner.dll from the Release directory to the GAC by dragging[1] it to the directory c:\windows\assembly using Explorer.
2
Make a directory to contain the MacawSharePointSkinner configuration file, for example c:\MacawSharePointSkinnerConfig. Copy the files SkinConfig.xml and SharePointSkinner.xsd to this directory.
3
Open the web.config files of the portal for which you want to enable the MacawSharePointSkinner functionality, and the SharePoint /_layouts virtual directory in NotePad or another text editor. Those files can be found in the virtual directory of the portal (when SharePoint is configured on the default web site, this directory is c:\inetpub\wwwroot), and the directory C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\LAYOUTS\web.config.
In step 3-10 the needed changes are described as the bold lines in the boxes. The other lines of the configuration file are there to give you the context where to find the place to do the modifications.
4
Enable support for an appSettings section:
<section name="appSettings" type="System.Configuration.NameValueFileSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" /><sectionGroup name="SharePoint">5
Add the appSettings section with the following keys:
MacawSharePointSkinner-ConfigFile
Path of the configuration file. Must be a directory path, not an URL.
MacawSharePointSkinner-Logging
‘on’ or ‘off’ to enable or disable debugging information in comments in the page
<appSettings>6
Add the MacawSharePointSkinner HttpModule:
<add name="MacawSharePointSkinner" type="Macaw.SharePoint.Skinner.Skin,Macaw.SharePoint.Skinner, Version=1.0.0.1, Culture=neutral, PublicKeyToken=efcf6ac388b9b555"/></httpModules>1.3 Final step
The final step is to modify the MacawSharePointSkinner configuration file SkinConfig.xml.
1.4 Alternative configurations
This section describes some alternative configuration possibilities for the HttpModule dll, and for the used configuration files.
1.4.1 HttpModule dll deployment
The procedure described above deploys the Macaw.SharePoint.Skinner.dll to the global assembly cache. This deployment has the advantage that you only need one step to deploy the assembly and it is available in all virtual directories. Disadvantage is that an IISRESET is needed to activate the DLL.
If you don’t want to deploy Macaw.SharePoint.Skinner.dll to the global assembly cache, you need to deploy it to the following bin directories:
- C:\inetpub\wwwroot\bin (the path to the SharePoint virtual directory)
- C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\ISAPI\BIN (to keep FrontPage working, and have skinning support on the help pages)
- C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\LAYOUTS\BIN (to have skinning enabled on all pages in the ‘/_layouts/’ directory)
1.4.2 Configuration files
It is possible to specify different configuration files for the different virtual directories in their corresponding web.config files. This allows for specific skinning configurations for the SharePoint virtual directory pages and the /_layouts virtual directory pages.
It is possible to specify a file pattern as a configuration file, instead of a single file. So for example if you specify c:\MacawSharePointSkinnerConfig\SkinnerSharePoint*.xml as configuration file in the web.config of the SharePoint virtual directory and c:\MacawSharePointSkinnerConfig\SkinnerLayout*.xml in the web.config of the /_layouts virtual directory, you can have multiple configuration files to define your skinning operations. This is used in large Share Point modification projects where each subproject has its own configuration files. Note however that the configuration files are read in undefined order, so make the configuration files as independent as possible of each other. Especially overlapping URL redirections can lead to unpredictable behavior.
If order of interpretation of configuration files is important, it is also possible to supply multiple configuration files separated by ‘;’ characters. For example: c:\MacawSharePointSkinnerConfig\mefirst.xml; c:\MacawSharePointSkinnerConfig\restoffiles*.xml
2 MacawSharePointSkinner configuration
2.1 Introduction
Configuration of the MacawSharePointSkinner is done in an XML file named SkinConfig.xml. This file can be found in a directory called c:\MacawSharePointSkinnerConfig or another directory as defined in step 2 of the installation procedure defined in section 2.2. This file can be edited in any text editor like notepad or in a special XML editor[2].
Within the configuration file regular expressions[3] are used extensively to define match patterns.
2.2 Structure of the configuration file
The structure of the configuration file is unambiguously defined by the corresponding XSD schema SharePointSkinner.xsd.
In this chapter some configuration examples are given
2.3 Skinning language
This section describes the skinning elements that make up the skinning language. The elements are given, and their hierarchy. Between brackets the occurrence count is specified.
(1)
exactly once
(0,1)
optional
(0,n)
zero or more times
(1,n)
one or more times
skinner (1)
default-uri-matchtype (0,1)
cache-time (0,1)
parameters (0,1)
parameter (1, n)
urlredirections (0,1)
urlredirection (0,n)
rules (0,1)
rule(0,n)
uris (1)
uri (1,n)
match (0,1)
parameters (0,1)
parameter (1, n)
texts (0,1)
text (0,n)
match (0,1)
parameters (0,1)
parameter (1, n)
blocks (1)
block (1,n)
match (0,1)
replacements (1)
replacement (1,n)
find (1)
replace (1)
Below is a detailed description of the available elements.
Element Description Skinner
Root element in the skinning configuration file.
default-uri-matchtype
Default way of matching for all match elements for uri.
Type Name Req. Possible values / description Attribute matchtype No RegExp|WildCard|Exact, not specifiedàRegExp Currently only the type RegExp is supported. This is always the initial default value.
cache-time
Time to cache the configuration file in seconds.
Type Name Req. Possible values / description Attribute duration Yes 0, -1, n Currently time expiration is not supported. Only the following values are supported:
0: the configuration is reread on every replacement (for testing purposes only)
-1: the configuration is never reread. A new initialization happens on IISRESET
parameters
Group element for specifying parameters using the parameter element.
parameter
Parameter definition that can be used for replacements in other elements like match, find and replace.
Type Name Req. Possible values / description Attribute name Yes Name of the parameter Value n.a. Yes Value of the parameter Parameters are replaced in the text of elements when the text {{parametername}} occurs.
urlredirections
Group element for specifying url redirections using the urlredirection element.
urlredirection
Url redirection definition that specifies how to redirect a matching target url to a destination url.
Type Name Req. Possible values / description Attribute name Yes Name of the redirection rule Attribute
permanent
No true|false. If true, redirections are done through an HTTP 301 response. This means an extra roundtrip to the server. Complete Url (http://servername/...) must be specified for the destination. Attribute enabled No true| false. If true this redirection is used, if not specified redirection is used Parameters are replaced in the text of elements when the text {{parametername}} occurs.
Target
Specifies the expression to match the target uri.
Type Name Req. Possible values / description Attribute matchtype No RegExp|Exact, not specifiedàRegExp Value n.a. Yes Expression to match. Regular expression match in CDATA section destination
Replacement for the matched uri. May contain captures and parameters.
Type Name Req. Possible values / description Value n.a. Yes Replacement text. Regular expression replacement in CDATA section rules
Group element for specifying rules using the rule element.
rule
Skinning is implemented by execution of rules. More than one rule can be defined. When a rule matches, skinning can stop at this rule or it can continue to match next rules. A rule contains two elements:
- uris specify the match the requested page must make on uri, text or both
- blocks to specify the replacements to be executed on the page if matching
Type Name Req. Possible values / description Attribute enabled No true| false. If true this rule is used, if not specified rule is used Attribute name Yes Name of the rule Attribute description No Description of the rule Attribute match-continue No true| false. If true continue matching next rules if this rules already matched, if false stop after match uris
Group element for specifying uri matches using the uri element. Within the uris element we specify which pages will match this rule, either on uri match or text match or both.
uri
Uri match. If no match element is specified all uris match. Parameters can be defined under the uri element that can be used in the block replacements.
Type Name Req. Possible values / description Attribute enabled No true| false. If true this uri is used, if not specified uri is used match (in uri)
Specifies the expression to match the uri. If this element is missing, all uris match.
Type Name Req. Possible values / description Attribute matchtype No RegExp|WildCard|Exact, not specifiedàRegExp Value n.a. Yes Expression to match. Expression match in CDATA section texts
Group element for specifying texts using the text element.
text
Text match. If no match element is specified the text always matches. Parameters can be defined under the text element that can be used in the block replacements.
Type Name Req. Possible values / description Attribute enabled No true| false. If true this text is used, if not specified text is used match (in text)
Specifies the expression to match the text. If this element is missing, the text always matches.
Type Name Req. Possible values / description Attribute matchtype No RegExp|Exact, not specifiedàRegExp Value n.a. Yes Expression to match. Regular expression match in CDATA section blocks
Group element for specifying blocks using the block element.
block
Block selection. If no selection element is specified the whole text is selected for replacements.
Type Name Req. Possible values / description Attribute name No Name of the block Attribute description No Description of the block Attribute enabled No true| false. If true this block is used, if not specified block is used selection
Specifies a selection for a block to do replacements on. If this element is missing, replacements specified in the block are executed on the complete text of the requested page.
Type Name Req. Possible values / description Value n.a. Yes Block selection. Regular expression in CDATA section replacements
Group element for specifying replacements in the block using the replacement element.
replacement
A replacement to be executed. Contains of a find and replace element.
Type Name Req. Possible values / description Attribute name No Name of the block Attribute description No Description of the block Attribute count No N, number of replacements to execute, if not specified then infinite Attribute enabled No true| false. If true this rule is used, if not specified rule is used find
Regular expression for the selection of text that may contain captures. Find text may contain parameters.
Type Name Req. Possible values / description Attribute matchtype No RegExp|Exact, not specifiedàRegExp Value n.a. Yes Expression to find. Regular expression match in CDATA section replace
Replacement for the selected text. May contain captures and parameters.
Type Name Req. Possible values / description Value n.a. Yes Replacement text. Regular expression replacement in CDATA section When it is specified to specify text in a CDATA section to prevent invalid XML, use the following syntax: <![CDATA[text]]>
3 Advanced Skinner configurations
Pages are skinned by the skinner if the following conditions are met:
- The page request is in a ASP.NET virtual directory
- The web.config file contains the Macaw.SharePoint.Skinner HTTP module
- The page request returns content of type text/html
If you have a page that returns for example XML (content type is text/xml) the page is NOT skinned.
If you don’t want a page to be skinned (and no comments added tot the top, even if there is no URL match), you can add skinnerskip=1 to the query string.
Example: http://server/default.aspx?skinnerskip=1
4 Regular expressions
4.1 Introduction
Matches, selections, finds and replacements are all done using regular expressions. There are multiple flavors available in regular expressions. MacawSharePointSkinner uses the .Net flavor. For more information on regular expressions have a look at:
Description Url .Net regular expression documentation
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/cpconregularexpressionslanguageelements.asp
Small overview of much used language constructs
4.2 Regular expression matching configuration
All regular expression matches performed in MacawSharePointSkinner are done with the following options enabled:
IgnoreCase Specifies case-insensitive matching.
Multiline Specifies multiline mode. Changes the meaning of ^ and $ so that they match at the beginning and end, respectively, of any line, not just the beginning and end of the whole string.
CultureInvariant Specifies that cultural differences in language is ignored.
To increase the performance of matching, all regular expressions are compiled when the configuration file is read.
4.3 Tools for regular expression construction
When constructing regular expressions I always utilize a regular expression construction tool. These tools allow you to specify a source text (use the ‘view source’ text of the page you want to do replacements on), a regular expression (including captures) and a replacement. The tool visualizes the matches in the text and the resulting text after the replacement.
See http://www.larkware.com/RegexTools.html for an overview of available tools. One of my favorites in “The regulator” (http://regulator.sourceforge.net).
4.4 Tips & tricks
This section contains some tips and tricks in smart regular expressions to perform skinning tasks.
4.4.1 Block selection of head
In one situation we had to replace the stylesheets within the head. These are four replacements. To improve replacement speed the replacements are done on a block that matches only the head section. The head can be matched as follows:
5 Using MacawSharePointSkinner
There are many, many usages for the MacawSharePointSkinner. Some examples of the usage of the MacawSharePointSkinner are:
- Apply different style sheets to different areas in the portal area tree.
- Remove system account from the “Assigned to:” dropdown boxes in the new and edit pages of certain lists (issues, tasks).
- Redirect access to certain pages in the /_layouts directory to your own, modified, versions of these pages.
5.1 Url redirections
Url redirections in SharePoint works different from url redirections with normal ASP.NET applications. SharePoint uses special handling of url’s, because it uses a kind of “in context” page access. Examples are the pages in the /_layouts virtual directory. If you request the url http://servername/sites/mysite/_layouts/1033/aclinv.aspx, you actually access the page /_layouts/aclinv.aspx, but in the context of the SharePoint site mysite.
Due to special handling in SharePoint, we also have to take this into account in specifying the url redirections.
If you want to redirect the page /_layouts/1033/aclinv.aspx to /_layouts/my1033/aclinv.aspx, do the following:
This redirection is performed “in context”, so in the destination page we are still in the same context.
If you want to redirect all access to the “in context” page /_layouts/1033/aclinv.aspx (for example http://servername/sites/mysite/_layouts/1033/aclinv.aspx and http://servername/sites/othersite/_layouts/1033/aclinv.aspx) to a page NOT in /_layouts, the complete url of the destination page must be specified, and the permanent attribute must be set to true (if target is full url, permanent is automatically set to true).
If you only want to redirect all access to the page http://servername/sites/mysite/_layouts/1033/aclinv.aspx (so NOT access to all /_layouts/1033/aclinv.aspx pages in any context), a complete url of both the target and destination page must be specified, and the permanent attribute must be set to true (if target is full url, permanent is automatically set to true).
6 Frequently Asked Questions
Q: MacawSharePointSkinner works great in my SharePoint sites and in the portal, but not for the pages in the /_layouts virtual directory. It also does not work for the help pages of SharePoint.
A: See section 2.2 for information on how to modify the web.config file to add the HttpModule. The procedure to add it to the /_layouts virtual directory is included in this section. For each virtual directory you want to skin you have to modify the web.config file. So for
Portal/Wss:
/_layout:
/_vti_bin (help pages):
[1] copy – paste does not work on the assembly directory, dragging is needed for automatic installation of the DLL in the GAC. The assembly can also be installed using the gacutil tool. In this case execute the following command: gacutil /i Macaw.SharePoint.Skinner.dll
This tool can be found in the directory C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322.
[2] Because the corresponding XSD schema file is provided, syntax checking on the XML can be used in XML editors like XMLspy and Visual Studio .NET 2003.
[3] If you don’t know what regular expressions are, go to Google, and in the search string type define:regular expression. See also chapter 4 for more information on regular expressions.