SPModerationInformation class

Moderation information is kept in separate class called SPModerationInformation. It has properties Status and Comment. First one of them shows moderation status of list item and the other one contains comment inserted by user who last changed moderation status. List item has property called ModerationInformation that returns this object.

SharePoint list versioning settings. First setting is for content approval. 
By default content approval is disabled. 

SPModerationInformation class does nothing special – it is only wrapper for two fields: _ModerationStatus and _ModerationComment (these are internal names of these fields). These fields are added to list when user enables content approval. If content approval is disabled then ModerationInformation property is always null for list items.

Querying list by moderation status

It is possible to query lists by moderation status using CAML queries. As I mentioned before there is field with internal name _ModerationStatus. In database and web services it is integer that keeps values from SPModerationStatusType enumerator. But if you are dealing with list items then this field contains string.

In CAML queries we must use moderation status as string.

You can see that we have to use special field type called ModStat. Yes, there is even class called SPFieldModStat for this type.

Awful bug in SharePoint

So far, so good, but this solution works only in english installations of SharePoint. If your SharePoint site uses some other language than english you are in trouble because query shown above doesn’t return items anymore. But it also doesn’t give you any errors.

Names of moderation statuses are not taken from SPModerationStatusType enumerator. There values are read from resource file!

Well, now consider what happens when somebody makes a little typo in one of those translations. I think I don’t have to mention that building code and process logic around translation variables is something we can expect from complete noobs.

Unified solution

To make these queries work in any SharePoint site we have to read correct values from resource file.

1. From Global Assembly Cache (GAC) copy assembly called Microsoft.SharePoint.intl.dll to some place where you can access it.
2. Run Reflector and open this assembly.
3. Under resources section you will find resources in this assembly.
4. Open Microsoft.SharePoint.resources, sort resources list and find constants that start with word ModerationStatus as shown on the image below.

.NET Reflector showing contents of Microsoft.SharePoint.resources. On the right pane
moderation status Approved is highlighted.

Now we want to use these resources in our code. Here is class that provides you with static properties that return correct values for _ModerationStatus fields.

Now you can write query shown above as follows.

This solution is nothing elegant but I don’t think there are completely nice ways to get around hacks without replacing them with correct code.

References

• Adding functionalities to pages by inheriting PublishingLayoutPage (Janne Mattila’s blog)
• HowTo use the resource files from SharePoint (SharePoint Blog – René Hézser)
• .NET Reflector home page

Related posts:

1. Querying SharePoint lists

Solution structure and scripts

To get scripts small and focused on conrete task we will create more than one batch file. It makes it very easy to create scripts for composite tasks – just add calls to base scripts and you are done. We will write the following scripts:

• build.bat – builds Visual Studio solution using MSBuild,
• package.bat – creates deployment packages for all projects using WSPBuilder,
• deploy.bat – deploys all solution packages to SharePoint,
• recycle-all.bat – recycles all application pools,
• replace-spsite.bat – replaces test site with new one if solution contains site template,
• full-build.bat – runs all previous scripts (you can call it also coffee-break.bat).

We also need some modifications to our Visual Studio solution. It is good practice to keep all external tools you are using in your solution also in source-code control. So we need solution folder for tools. And we also need another solution folder – we need a place for scripts too. You can see Tools and Scripts folders on the image above. This image also illustrates Visual Studio solution folder structure.

NB! Scripts provided here are very raw but they work. At least for us. There is lot of room for these scripts to be improved and optimized.

Build script

Build script will build Visual Studio solution. This is the first script we run when we start replacing our test site. I am using MSBuild because it turns out to be easiest tool for this task and also it is also in your computer if you have Visual Studio installed.

As I have currently no more actions related to code building then one line is enough from me.

You can add all other build related commands to this file too.

Packaging script

After build we need to create new deployment packages for solutions. We will use WSPBuilder command-line tool that creates solution packages and deployment scripts. Here is the packaging script.

...

Tools\WSPBuilder.exe -SolutionPath Projects\ProjectN -ProjectPath Projects\ProjectN -OutputPath Projects\ProjectN -ExpandTypes true -CreateDeploymentFolder stsadm


Notice that WSPBuilder is put into Tools folder and called from there. Also notice that there is packaging command for each project in solution that needs packaging.

Recycle script

Well, recycling application pools can be done also on one line but it is not very sure I will use same recycling mechanism forever from now on. Also it is possible that same tools are not available on some development environments.

This recycle method works well if you have IIS 7.0.

Deployment script

Deployment scrip deploys all our solutions to current SharePoint server. It is the slowest script and I don’t suggest it to run without good reason. It uses global deployment so all solutions regardless of their contents get deployed for sure. It is also compatible to deployments that WSPBuilder allows you to do through Visual Studio IDE.

Before using this script we have to copy gacutil.exe to Tools folder. Before deploying solution to SharePoint the script removes all related assemblies from Global Assembly Cache (GAC). To make sure that there is no instances of assemblies anymore used by SharePoint iisreset is called.

Now take a look at two deployment call blocks shown above. First one of them makes global deployment to SharePoint. ProjectN will be deployed to all content applications automatically. It depends on your Visual Studio project contents what kind of deployment to use.

Site replacement script

Site replacement script is optional. My solution contains site definition that gets updates couple of times per day and I have to test if sites created by this definition are created correctly. Best way to test it is to create a new site. I prefer keeping things simple in my development machine so I delete site collection and create it again based on my site definition. Here is my script.

call "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\stsadm.exe" -o createsite -url http://mossdev -owneremail me@example.com -ownerlogin mossdev\Administrator -lcid 1033 -sitetemplate SiteDef#0


Consider hard if you want to run this script for update deployments because this script deletes site and all its subsites and creates new site based on given site definition.

Full-run script

Our last script is for full run. It buils, packages, deploys our solution and replaces site collection. Script is simple because it calls other scripts we wrote previously.

You don’t have to run these scripts for all builds because they take some time to complete. If you are modifying only some web parts and you need to get them online then do it through Visual Studio IDE.

Conclusion

As you saw it is not hard to write build and deployment scripts. You saw also that using powerful tools keeps your scripts simple. Of course, scripts provided here are just examples of what is possible. You should write your own scripts for your own scenarios.

References

• WSPBuilder homepage
• MSBuild reference
• MSBuild Team Blog
• Stsadm command-line tool

Related posts:

1. Moving SharePoint solutions from VSeWSS to WSPBuilder

VSeWSS is great tool by idea but it causes for me heavy performance problems when I develop SharePoint solutions that contain more modules. Also I face serious performance problems when developing VSeWSS based projects on virtual machines. VSeWSS 1.3 was pretty hard to install and configure in my environments and I decided to abandon it. WSPBuilder introduces sometimes only some minor problems that are very easy to get over.

Let’s suppose we have Visual Studio solution that contains couple of web parts. Solution uses VSeWSS based SharePoint project. We don’t have VSeWSS installed on our machine but we have WSPBuilder. We will modify project file and project structure. I show you on one web part what exactly to do.

1. Modify project file

When you open VSeWSS project you get the following error message.

Visual Studio is not able to detect project type because you don’t have VSeWSS installed on your machine. WSPBuilder uses typical class libraries and doesn’t expect any additional project types to be installed or applied to project. Now follow these steps:

1. Click Okay. Message disappears and project is shown as disabled in Solution Explorer.
2. Right click on project and select Edit your-project.csproj.
3. Project file will be opened in XML-editor.
4. Look for ProjectTypeGuids tag. It should look like this:
   

   ---

   <ProjectTypeGuids>{593B0543-81F6-4436-BA1E-4747859CAAE2};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>

   ---

5. Remove first GUID and semicolon from GUIDs list:
   

   ---

   <ProjectTypeGuids>{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>

   ---

6. Save project file and close it.
7. Right click on project file and select Reload Project.
8. Project should load now and you should see its contents in Solution Explorer.

2. Modify project structure

WSPBuilder expects project structure that is more similar to that you can find under 12-hive. You have to create also folder for your solution features and create feature files. Although VSeWSS creates feature files automatically I am not happy with it – I don’t need feature per web part in project. Usually one feature is enough.

Here is new project structure that is okay for WSPBuilder. As you can see form Solution Explorer screenshot the folder structure is same as under 12-hive.

I put all web parts in project under same feature – EventsWebParts. If you want you can also definer more than one feature per one project. WSPBuilder will handle the situation without problems.

Currently I expected that you moved existing web part definitions to your feature folder as shown on screenshot.

3. Creating Feature.xml

Let’s create now Feature.xml file. File creation process is like for any other file type in Visual Studio. Right click on your feature folder, select Add new … and then Data and XML file. Name file as Feature.xml and you are almost done.

In your feature file you must define elements and manifests locations. You can take the following example and modify it.

4. Modifying web part files

If you are using web part definitions created by VSeWSS you need to modify files with .webpart extension. Open some of these files in Visual Studio. You should see something like this.

Take a look at type tag under metaData. There is GUID of web part that this file defines. The same GUID is assigned to web part in its code file. When you build solution package with VSeWSS then VSeWSS replaces this GUID automatically with web part’s full type name. WSPBuilder is not able for that currently, so you have to replace the GUID in web part file with web part’s full name.

5. Test

Now you are almost done. Build your project and deploy web part to SharePoint.

1. Right click on project title in Solution Explorer.
2. Select WSPBuilder –> Create Deployment Folder.
3. WSPBuilder build solution package and generates installation scripts.
4. Select WSPBuilder –> Deploy.
5. WSPBuilder deploys your solution to SharePoint.
6. Open SharePoint and try to add your web parts to some page to make sure that package was built correctly.

Epilogue

Although VSeWSS is built with good intentions it offers very basic functionality and has sometimes serious performance problems. Newest version is harder to install and configure than older versions. WSPBuilder is free and open-source utility that works very well and doesn’t cause problems in development environment. It is very easy to install and use. To save your time you should think about moving to WSPBuilder if you are not using it already.

References

• WSPBuilder homepage
• WSPBuilder support forum
• Carsten Keutmann’s blog (author of WSPBuilder)
• VSeWSS 1.3 download page 
• VSeWSS 1.2 download page

Related posts:

1. Writing build and deployment scripts for SharePoint solutions

I also put it up to CodePlex and named it as SPGenerateFileDefinitions.

Here is screenshot of application’s only screen. All you need is there – just make couple of mouse clicks and your work is done.

How to use

1. Download application from project page in CodePlex.
2. Unpack it and run SPGenerateFileDefinitions.exe.
3. Click on button […] and show where are files located.
4. Click on button [Create XML].
5. When definitions are done click [OK] on message box.
6. Put definitions to your feature files using copy and paste.

SPGenerateFileDefinitions is new tool and currently we are updating it if we need more features. If YOU need more features, then please let us know about it in project discussion. If you find bugs or you have problems with SPGenerateFileDefinitions then please submit all this feedback to our issue tracker. And as a last thing – happy using!

Unified Logging System

WSS 3.0 and MOSS 2007 both use Unified Logging System (ULS) to write messages to SharePoint log. ULS uses Event Tracing for Windows (ETW). This is logging and tracing technology first introduced in Windows 2000. ETW is available through Windows API and it should be very efficient logging technology.

Although ULS is powerful technology it is not easy to use without third-party tools. You can configure some settings in SharePoint Central Administration site but there are no default tools that make reading the logs easy.

References

• Configure diagnostic logging settings (TechNet)
• SharePoint Debugging and Logging Tips and Tricks (Andrew Connell)

How to read log files

You can use different tools to read and analyze SharePoint log files. All log file reading tools introduced here are third-party tools from CodePlex and other sites. They work nice and if you find something you like you can try it.

Starznet WSS / MOSS Log File Reader

Starznet WSS / MOSS Log File Reader is SharePoint solution that you can install to Central Administration web site. It adds new “Log File Viewer” selection under “Logging and Reporting” block. Following screenshot gives you some idea about what to expect. Most useful feature that Starznet offers is log files search. I know what a pain can be searching and reading log files using Notepad or some other simple text editor.

Starzner WSS / MOSS Log File Reader. Screenshot shows file contents view.
Click on image to enlarge.

I got it installed without any problems and it works nice. I found also one problem – Log File Reader is not able to read current log file because of file locks. 

SPTraceView

If you need something very simple to monitor your logs in real-time, you can use SPTraceView utility by Hristo Pavlov. SPTraceView also offers table view of active log file and you can open it by double clicking on trace icon.

SPTraceView has also settings dialog where you can modify logging level and message filters. It is also possible to send selected messages to DebugView. I think SPTraceView may be useful tool for developers to track problems in test environment. It is faster than monitoring log files manually.

Microsoft Log Parser 2.2

Microsoft Log Parser is command-line tool you can use to analyze ULS log files. Log Parser lets you execute queries against ULS log files and save output to another text file. Performance of this tool is pretty good. MSDN blog entry ULS Log File Data Mining gives example of query that uses aggregate functions and that handles almost 1.5 million log lines with 77 seconds.

You can use this tool to execute your own SQL-like queries against log files to get out information you really need. There is one gotcha – Log Parser doesn’t know that log messages in ULS logs may take more than one line.

References

• Starznet WSS / Moss Log File Reader (CodePlex)
• SharePoint ULS Log Viewer  (CodePlex)
• SPTraceView – Lightweight Tool For Monitoring The SharePoint Diagnostic Logging In Real-Time (Hristo Pavlov)
• Microsoft Log Parser 2.2 (Microsoft)
• ULS Log File Data Mining (MSDN blogs)

How to write to log files

Writing to SharePoint log files from your is simple if your code has to run only on MOSS 2007. It takes only one line of code.

That’s it. But if you are using WSS or you want logging solution that works for both of them, you need third-party libraries. Of course, you can write your own logging solution if you have time enough. There is third-party library called SharePoint.Diagnostics that let’s you do something like this.

There are some tricks to make it work. After downloading WSP change its extension to cab. Extract SharePoint.Diagnostics.dll and add reference to it to your project.

References

• ULS Logger (CodePlex)
• SharePoint.Diagnostics (CodePlex)
• SharePoint: Writing messages to ULS (Unified Logging System) (My ASP.NET blog)
• SharePoint Trace Logs and the Unified Logging Service (ULS) (Eli Robillard)
• SharePoint Logging and Microsoft’s Trace Log Provider (Trentacular)
• Trace Logs (MSDN Library)
• Trace Log Example (MSDN Library)
• SharePoint Diagnostic Logging (ak ULS) Quick Summary (Full Metal Architect)
• Implementation of Logging and Instrumentation Application Block in MOSS 2007 (CodeProject)

Epilogue

ULS logs are powerful sources of information. Reading and writing SharePoint logs lies heavily on third-party and custom solutions right now. With free and open-source third-party tools it is easy to read and write SharePoint logs. Developers can easily write messages of their extensions to SharePoint logs and this makes extensions to fit better in SharePoint environment.

Preface

Before we start querying our first list you must understand SharePoint list structure. Every list in SharePoint contains some built-in fields what are created out-of-box and other fields you create your own purpose. Every field in this list has its own data type and may have been associated with special SharePoint field class (e.g SPFieldLookup, SPFieldUser), which you can use to get values or specify field’s metadata. Every item returned from the query is in object type and must be casted into right field type before usage. Every query you make to the list returns SPListItemCollection object where you can use indexer to get specific SPListItem or you can iterate the item collection using foreach.

Every field in a item’s field collection contains two type of naming to programmatically use. There is field’s internal name – this name will not be changed after creation, and is the best way to query specific field; and display name or title – what you can change in the UI. Display name is not the best way to query fields in code, because when somebody changes it you will get an exception which is not very useful to debug and may take a lot of your time to find this bug. When you create a field in the UI, the new field will have the same name for the internal name and display name, when you modify a field in UI you only change a display name. To programmatically access this field you must use the field name you assigned first time.   

Query options

To begin with querying list you have two options to get results out of list. You can use SPList object methods and properties to ask items from the collection or you can use CAML (Collaborative Application Markup Language) to specify fields and filters.

NB! You should not use SPList.Items property with the large list, because it will return all the  items in the list with all fields. Query results are not cached and it will be a performance hit to your server because every time you query some items, SharePoint will create a new collection for your items.

So to start with our first example I will show to you how you can get the first item’s field value from the Items collection using field’s display name “MyField”.

To use internal name in this example we will create SPField object which will allows us to use all the field metadata. We will use SPField Id property to get item field value.

To get the best performance out of querying lists you should use CAML queries. It will allow you to choose fields you want to show, result items count and filters.

Basic CAML query syntax is:

To use CAML in our queries we have to create SPQuery object. SPQuery object allows us to specify other parameters of query such as: ViewFields, RowLimit.

In our next example I will create CAML query to get list items where “Status” field value is “Archived”

To specify how many items to return you should add line:

To show only fields “Title” and “Status” you should add line:

Exceptions

You must choose a the type of query always carefully, because if there is some mistake in field’s display name or internal name SharePoint gives you the most generic message e.g “Value does not fall within the expected range” or “One or more field types are not installed properly. Go to the list settings page to delete these field” To avoid these exceptions you should always use internal name because it can’t be changed after creation.

To avoid field name mistakes you should always create list instance based on list template or list definition. It avoids mistakes that people can do when installing your solution and allows you to specify internal name you like.

In Conclusion

Lists are important tool in our everyday programming and it is important to know how to query items from lists. Using Items collection will help you quickly to get all the items in the list, but it will be a performance hit when you use it on a large list. To specify how many items to show, which fields to use, you should use CAML queries.

References

• Getting List Items
• CAML queries for getting list items
• CAML Query Schema
• Querying lists using CAML

Related posts:

1. Dissecting SharePoint content approval

WSPBuilder

The most important tool in the SharePoint solution development lifecycle is a solution package creator. WSPBuilder is a simple solution package builder which will integrate with Visual Studio 2005 and 2008. It will allow you to create, install, upgrade and uninstall your solution package (WSP) and even create deployment folder which contains deployment scripts and installation program. After you install this tool it will create a new menu item and context menu into your Visual Studio (VS) environment.

WSPBuilder is quite dynamic with its capabilities. You can start your project with a simple class library, it won’t add mysterious dependencies to project which won’t let you to open your project in another VS environment. Only requirement that WSPBuilder needs is that you have to create your project folder structure like in the SharePoint 12 hive “C:\Program Files\Common Files\microsoft shared\Web Server Extensions\12”

SharePoint Solution Installer

After you have created your project solution package you can use a nice installer, which will help your application users to install the application.

It is much simpler than using SharePoint built-in administrative tool stsadm.exe. You can create custom End User Licence Agreement file and add it to installer. You can even specify which features will be activated. Before you can install your solution installer will check your system to meet te requirements (MOSS or WSS application, application installed or not).

SharePoint Manager 2007

Sometimes you need get some list item field internal name or you want to add some list definition into your project and make some modifications. Usually to get some property value from list or list item is impossible because property is hidden in the UI and you cant find the value from the site or list template. SharePoint Manager will help you with these problems.

It is a nice tool what you can use to find properties, schemas, etc. from Site Collection, Web, List, etc. SPM will help you to check if your code run as expected and it did set the workflow association data. With SPM you can make even changes to some properties, but you must be careful with that and you have to know what are you changing and what value the property expects.

Conclusion

Every tool in this list has somehow helped me in my development. I’m using SP Installer because it is simple and it will allow change the installer experience by simply changing some property values in installer configuration.

SharePoint Manager is a create tool to check some property values, internal names, to get minimal list schema and it will allow me to do this without opening SharePoint site.

WSPBuilder is the simplest package creation tool I have seen, it allows me to create multi-project solution and simply referencing assemblies it will create a nice package with everything my application needs.

Other tools

• Visual Studio Extensions For Windows SharePoint Services 1.2
• Simple Tools For SharePoint 2007 Development

Related posts:

1. Moving SharePoint solutions from VSeWSS to WSPBuilder