Archives

Archives / 2006 / January
  • 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-403e6af7fa11 UPDATE: 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:

     :<configSections>
        <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

     :</configSections> 
    <appSettings><!-- MACAW: configuration for MacawSharePointSkinner --><add key="MacawSharePointSkinner-ConfigFile" value="c:\MacawSharePointSkinnerConfig\SkinConfig.xml"/><add key="MacawSharePointSkinner-Logging" value="on"/><!-- MACAW: end of configuration for MacawSharePointSkinner --></appSettings>
         <SharePoint>  :

    6

    Add the MacawSharePointSkinner HttpModule:

     :<httpModules>  <clear />  <add name="OutputCache" type="System.Web.Caching.OutputCacheModule" />  <add name="WindowsAuthentication" type="System.Web.Security.WindowsAuthenticationModule" />  <!-- <add name="Session" type="System.Web.SessionState.SessionStateModule"/>-->
      <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.I false, the redirection is done within the same application domain (same virtual directory)
    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

    http://www.regexlib.com/CheatSheet.htm

    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:

     <selection><![CDATA[<head>(?:.|\s)
    ?</head>]]></selection>

    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:

     <urlredirection name="aclinv.aspx"><target>/layouts/1033/aclinv.aspx</target>      <destination>/layouts/my1033/aclinv.aspx</destination></urlredirection> 

    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).

     <urlredirection name="aclinv.aspx" permanent="true"><target>/layouts/1033/aclinv.aspx</target>      <destination>http://www.disney.com</destination></urlredirection> 

    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).

     <urlredirection name="aclinv.aspx" permanent="true"><target>http://servername/sites/mysite/layouts/1033/aclinv.aspx</target>      <destination>http://www.disney.com</destination></urlredirection> 

    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.