Ingo Karstein's Blog @ kenaro

SharePoint 2013 List Forms: New Small Framework Project to Store List Forms in SharePoint Library (Part 1)

I spend some spare time in the last weeks and the last days (in Redmond before the MCSM: SharePoint rotation starts in a few hours 😉 ) for a new private development project. It focuses on custom list forms for SharePoint 2013. – Another article of my blog is one of the most recognized one regarding to the statistics: https://blog.kenaro.com/2010/12/29/walkthrough-create-custom-sharepoint-2010-list-form-for-deployment-in-a-visual-studio-2010-project/ – So I decided to write another article in this context in connection with another plan of mine to create a small framework to enable custom list forms that are stored directly in a SharePoint document library and which are connected with the content types automatically.

I release the source code there:

http://splistforms.codeplex.com

There is no “binary distribution”, because it’s “alpha“. – You will use it at your own risk – as always. Remember: It’s a private development project and I publish it for demonstration purpose only!!

These are the goals:

Create a SharePoint list where list forms for content types are registered. – When creating a new form in this list it gets automatically registered on the content type.
The list form has 3 different form modes: New, Edit, Display. All can be set individually.
The list forms are rendered by using controls stored in a SharePoint document library. – The default SharePoint “Rendering Template” mechanism is used.
The custom list form control can be edited with SharePoint Designer or by using another Editor by opening the control file in a mapped network drive.

All this based on SharePoint rendering templates. There are lot of articles out there that cover that topic.

Some information here:

Each content type in SharePoint has some properties related to “form templates” that can be set using C# or the declarative way.

Let’s have a look into the settings of the content type “Item” of a simple custom list.

Here you see all form templates are set to “ListForm”. That is the default setting. – Other lists such as task lists use different default settings like this:

“ListForm” and “TaskForm” are so called “rendering templates” that is taken from a certain file in the 15 hive: <15>\TEMPLATE\CONTROLTEMPLATES\DefaultTemplates.ascx

Looking into the file:

Here you find the rendering template “ListForm”. It defines how to create the forms HTML codes at rendering time. – Look at the “ListFieldIterator” tag. It will generate HTML code for all the fields in a SharePoint list. It’s very generic!! (The whole rendering mechanism is one of my favorite peace of code of SharePoint J )

Also for rendering the fields (“columns”) there are rendering templates that will be used by the “ListFieldIterator” at some point of rendering. For example:

You can create your own rendering templates for use with content types. Just add a .ASCX file to the CONTROLTEMPLATES folder of the 15 hive that contains a rendering template in this fashion. (You cannot use a sub folder below CONTROLTEMPLATES!!) Then set the property of the content type to the rendering templates name and it will be used to render your list form. – This is what my framework does.

In the first article I want to show you the result of this project.

In the second article [coming soon] I want to show you how it works behind the scene of the framework.

In the third article [coming soon] I want to show you how to create a SharePoint project to deploy custom list forms that uses the framework.

Let’s start…

1. To start the demonstration I need to create a simple custom list with some columns. I name the list “Simple Demo List” and create 4 columns:

“Date” => date and time column
“MultiText” => multiple lines of text column
“User” => person or group column
“YesNo” => Yes/No column

2. This is how the default new form of the list looks like:

3. Now I want to create my own list form for this list using my brand new framework. – Therefore I want to show you the two lists and one library it consists of:

“List Forms” : This list contains all custom form registrations made by the framework. Here you can create new forms. An event handler will create the controls derived from the chosen templates register them on the content types.

“List Form Controls” : This library contains the list form controls, the templates and additional jQuery libraries.

“List Form Templates” : In this list you can register new templates that will be used to create new forms.

This is a simple list that refers to the “Templates” folder of the “List Form Controls” library:

4. Now I want to create a “New Item” form my “Simple Demo List”. Therefore I add a new item to the “List Forms” list:

Here you enter all information needed to identify the content type for which you want to create form. You can choose a form template. I have included to kinds of templates:

Plain templates that use the same rendering template as the SharePoint default “ListForm” template.
jQuery enabled form templates that allow you to use jQuery for customizations.

I choose “New jQuery” as template.

Before we hit “Save” let’s have a look at the content type using PowerShell. (It’s the same screenshot as above in the “rendering template” excursion at the beginning of this article…)

All forms are set to their defaults: “ListForm”

Now I hit “Save” on the new “List Forms” list item to create my own form.

After that the list view of “List Forms” looks like this:

What happens here:

The chosen template file is taken from the “Templates” folder of the “List Form Controls” library. A new name is created using the naming template “SimpleDemoList-New-<GUID>”. The new control is saved using this name in the root folder of the “List Form Controls” library.
Inside the new control file there is a template for the list columns. This template will be taken and reproduced for each (visible) field (list column). Then the template in the new control file is replaced by the list column entries. – Here is the template file:

The whole template between the marks “LISTFORM_FIELDPLACEHOLDER_BEGIN” and “LISTFORM_FIELDPLACEHOLDER_END” will be instantiated for each list column. Inside all marked placeholders (“LISTFORM_FIELDINTERNALNAME”) will be replaced by the list columns internal name.
Than a new rendering template is registered on the list content type “Item” on the “Simple Demo List”. – Let’s look into it using PowerShell again:

Now the “NewFormTemplateName” is “ListFormNew379E”. This is the indicator that my framework will be responsible for rendering the list form.
Let’s have a look into the “List form Controls” library. Here you will find the new control:
I open the control using a mapped network drive:

In it you see HTML code sections for each list column. These entries are generated automatically using the template file and the “item template” inside the template file.

5. Now let’s use the new form. Just open the list view of “Simple Demo List” and hit “New Item”.

This is our jQuery enabled form!! It works in an instant!!

The text “jQuery loaded” is generated at runtime when jQuery could be loaded. (This can be removed of course.) – This framework supports loading jQuery from library “List Form Controls” if it’s not present though the page, e.g. the master page. It also supports loading additional libraries.

To support jQuery and to allow you to use if for your own purpose there are two controls in the control file:

The first one (“LoadJQ”) is responsible for loading jQuery and additional libarires. (One library per line in “AdditionalLibraries”. Supported placeholders are: “~site” for the server relative site collection URL and “~web” for the server relative web URL.)

The second one (“JQSupporter”) can be used to store own code. As an example I’ve replaced the default “PreSaveItem” handler of SharePoint with my own handler in order to support my own validation mechanism before saving the item to be able to cancel the save action.

6. Now I want to add some new functionality to my control. Let’s say we want to ensure that title has at least 10 characters.

Therefore I modify the JQSupporter control in the control file using Expression Web 4 on the mapped network drive.

The “$$” I’ve used there will be replaced at rendering time with the ASP.NET ClientID of the List Form. This should be used to prevent naming issues. (To use “$$” as characters inside the script just use “\$$” as escape sequence.)

The variable “listform$$_ctrl_Title” is generated automatically by the JQSupporter control. For each visible list form control you will get such a variable “listform$$_ctrl_<FieldInternalName>“.

This is how the source looks like at client side:

Let’s test it:

It works. J

7. Now you are able to customize forms very quickly. “Normal” users only need read permissions on the lists/library “List Forms”, “List Form Controls”, “List Form Templates”.

All settings should be part of a normal SharePoint backup, e.g. Backup-SPSite. I’m not sure it would be part of an SharePoint Export. … I checked the exports Manifest.xml file and I can see the content types form setting is exported. Because of all controls and settings are in SharePoint lists and libraries it should be possible to include this in a SharePoint Export/Import or deployment process. – It should be possible too to save the settings in a site template. (However… you always need to add the SharePoint solution as full trust solution to your farm.)

Limitations:

It’s alpha!!!!!!!!!!!!!!!!!!!!!!
It is hardly tested!!!!!!!!!!!!!
It does not support removing the custom form from the content type. – That can be done through PowerShell by setting the form property back to the default value (“ListForm” or “TaskForm” or what ever…).
It should work with site content types but I’ve not tested it yet. I have commented out it.
It does not handle errors if they occure.
It’s not performance tested!
It has no management interface. Only the lists and libraries I’ve described above. They should be hidden. You could hide them easily.

Next steps:

Management interface
“Remove List Form” support for event handler on list “List Forms”
Field Rendering Templates.

Please feel free to make comments if you like it – or not like it.

InfoPath error & solution: InfoPath cannot open the following form … The file is not a valid XML document.

Yesterday I had a problem on a new SharePoint 2013 farm that took me some hours to solve it.

Problem:

I was not able to customize forms (again) using InfoPath on lists after creating them before sucessfully.

Steps to reproduce:

First I created a site collection and a custom list in it.

Than I use the “Customize Form” button in the Ribbon menu. The new form opens in InfoPath designer.

Than I modify the form and publish it.

In the browser I verify it’s working.

Than I want to change the form and click the Ribbon button “Customize Form” again.

Now this happens:

Error Message:

InfoPath cannot open the following form: http://sharepoint.local/sites/test/Lists/My New List/Item/template.xsn
The file is not a valid XML document.
DTD is prohibited.
Line 1, Position 9

When opening the URL of the InfoPath template in the browser I get this error from the Forms Server:

(Normally there would be a download dialog.)

Solution

It’s so simple… 😉 – After some network, log and code analytics I could figure out that you need…

… a site collection at the web application root!

Remember the first screenshot above. There I showed you the possible locations for the new site collection. As you can see the root “/” is available. This means: There is no site collection at the web app root.

After creating a site collection at the web application root I’m able to customize the list form with InfoPath. – After doing so:

Problem solved 🙂

My friend and colleague Guido could reproduce the problem and validate the fix. – @Guido: Thank you (and have a good week while teaching SharePoint 😉 )!!!

Hints

As far as I have seen there are other solutions related to the same problem:

Check your user has at least Contribute rights on the site.
Check your site is in “Local Sites” or “Intranet” zone of the Internet Explorer.

Guest Blog Article on Hey, Scripting Guy! Blog – Weekend Scripter: Run C# Code from Within PowerShell

http://blogs.technet.com/b/heyscriptingguy/archive/2013/03/30/weekend-scripter-run-c-code-from-within-powershell.aspx

Link to “C#Script”: http://gallery.technet.microsoft.com/C-Script-Execute-plain-a9eae961

UPDATE 2021-06-23: Found in backup. Now on GitHub: https://github.com/ikarstein/csscript

Guest Blog Article on Microsoft Blog “Hey, Scripting Guy!”: Learn About Using PowerShell Value Binding by Property Name

http://blogs.technet.com/b/heyscriptingguy/archive/2013/03/25/learn-about-using-powershell-value-binding-by-property-name.aspx

Update of PS2EXE: Version 0.4 now support Single and Multi Thread Apartment and “NoConsole” mode

On Codeplex user redpark asked for “Single Thread Apartment” mode (http://ps2exe.codeplex.com/discussions/435946)…

Here it is…

Please see v0.4 on CodePlex:

http://ps2exe.codeplex.com.

There are 3 new parameters:

-sta

Single Thread Apartment mode

(see http://msdn2.microsoft.com/en-us/library/system.stathreadattribute(VS.71).aspx)

-mta

Multithread Apartment mode

(see http://msdn2.microsoft.com/en-us/library/system.mtathreadattribute(VS.71).aspx)

-noconsole

resulting EXE is an Windows application not a console application.

The –noconsole parameter lets you create a Windows application EXE file with no console window.

Therefore I would need to implement several extensions for the PowerShell host included in the resulting EXE but currently I have not enough time to do this. But for now I’ve implemented the credential prompt so cmdlet Get-Credential will work as expected.

Update of PS2EXE: Version 0.3.0.0 Now Supports PowerShell 3.0 and 2.0!

Some time ago I’ve written a little tool called “PS2EXE” that creates .EXE files from PowerShell script files. As mentioned in earlier posts this is no conversation of PS to EXE! The PS2EXE script creates an EXE by using the C# compiler and stores the script as Base64 encoded string inside a tiny PowerShell host application.

Today I’ve updated the PS2EXE script to version 0.3.0.0. Now it supports PowerShell 3.0 and PowerShell 2.0.

https://github.com/ikarstein/ps2exe

(Formerly: http://ps2exe.codeplex.com)

Here are the past blog articles:

There are two new parameters for PS2EXE:

-runtime30

-lcid <int>

Using -runtime30 or by starting PS2EXE in a PowerShell 3.0 environment PS2EXE creates a EXE file by using the C# compiler version 4.0.

Using -runtime20 or by starting PS2EXE in a PowerShell 2.0 environment PS2EXE create a EXE file by using the C# compiler 2.0.

-lcid sets the “culture” of the current thread to the specified value. (See http://msdn.microsoft.com/en-us/library/system.threading.thread.currentuiculture.aspx and http://msdn.microsoft.com/en-us/library/system.threading.thread.currentculture.aspx and http://msdn.microsoft.com/en-US/library/w4deeh00(v=vs.80).aspx and http://msdn.microsoft.com/en-us/goglobal/bb964664.aspx.)

The new version should fix the “Assembly not referenced” error discussed here:

http://ps2exe.codeplex.com/discussions/404546

On Windows 8 or Windows Server 2012 there is PowerShell 3.0 installed by default. On Windows 7 or Windows Server 2008 R2 you can install it using Windows Management Framework 3.0.

With PowerShell 3.0 installed you will always start the 3.0 enviroment by using:

the Start Menu (or Screen)

the “Run” dialog:

the command line:

Execution PS2EXE reports PowerShell version 3.0:

You can start a PowerShell 2.0 enviroment by using this parameter: -version 2.0 for POWERSHELL.EXE

Execution PS2EXE reports PowerShell version 2.0:

Now lets use to create an EXE file using the PS2EXE script…

1. Sample: PowerShell 3.0 without parameters –runtime20 and –runtime30

2. Sample: PowerShell 3.0 with parameter –runtime20

(Behind the scene this starts PowerShell.exe using parameter –version 2.0.)

3. Sample: PowerShell 2.0 without parameters –runtime20 and –runtime30

4. Sample: PowerShell 2.0 with parameter –runtime20

This is not supported!

PDF UPLOAD METADATA EXTRACTOR (sample SharePoint 2013 & 2010 project) on Codeplex

When you upload MS Office documents to SharePoint document libraries their document titles are used in SharePoint to set the default Title column of list item of the uploaded document.

This does not work for PDF files, but it’s easy to reproduce the functionality.

I have created a simple VS2012 SharePoint project. It’s based on the C# (“iTextSharp”) version of the community version of iTextPDF (http://itextpdf.com) that can be downloaded here: http://sourceforge.net/projects/itextsharp/files/itextsharp/.

You can download source code and solution packages (“binaries”) from Codeplex:

http://sppdfmetadataextract.codeplex.com/

The project is published under LGPL license because iTextSharp v4.1.6 requires that. – The latest version of iTextSharp (5.3.4) is published under AGPL. Codeplex does not provide AGPL licencing. So I had to use the last version of iTextSharp published under LGPL.

Description:

1. On (Web-) feature activation an feature event receiver iterates through each document library in the web that is not hidden.

2. For each of them the feature event receiver registers a list item event receiver that fires on “ItemAdded” events.

3. Furthermore an list item receiver is installed for the web to fire on “ListAdded” events to register the list item event receiver mentioned before on newly created lists.

4. During upload of files to document libraries the list item event receiver look for files ending with “.pdf” (case insensitive).

5. If there is such an file it opens the file using iTextSharp library and reads its “Title” information.

6. This information is set for the default “Title” column of the SharePoint list item.

7. The change is commited by “SystemUpdate” on the SPListItem object.

8. If an error occures inside the event handler there is no action. The user will never see an error in the module. If it is not possible to extract the title of the PDF document the module will not set the title column of the list item.

Usage:

To use the feature just deploy the SharePoint Solution Package (WSP-file) to your SharePoint farm. It’s not a “sandboxed solution”! After that you need to activate the feature in each web where you need it. If you need to activate it on each new web you could use “feature stapling” to activate it by default. If you need this please write me an comment.

Demo in SharePoint 2010:

1. Create a Word document with a title and save it as PDF:

2. Check the document title by using Adobe Reader or Adobe Acrobat or any other PDF reader

3. First try to upload the DOCX and it’s PDF into a document library without the new feature activated on the web:

As you can see: The “Title” of the DOCX is used for the Title column of the SharePoint list item. For the PDF file the Title column is empty.

4. Now activate the feature:

5. After that delete the files uploaded before in the document library. Than upload both files again:

Now both “Title” columns are set!

6. My last test is to create a new Asset libary in the web. Than I upload both files and check the PDF’s properties:

The Title column is set as expected!!

Demo in SharePoint 2013:

I’ve added a second project just for SP2013. Here is a single screenshot…

SharePoint 2013 Design Packages: Import with PowerShell (Part 2 of 2)

Last Thursday I wrote about “Exporting SharePoint 2013 Design Packages with PowerShell”. Today I’d like to show you the import function. This functions can be used to handle with SharePoint 2013 Design Packages with PowerShell, e.g. in deployment scenarios. Therefore it should by very useful. (I hope so 😉 ) FEEDBACK WELCOME!!!

You can download the scripts here:

http://gallery.technet.microsoft.com/Export-and-Import-0f41b376

Here you can find the blog article about “Export-SPDesignPackage”: https://blog.kenaro.com/2013/02/14/sharepoint-2013-design-packages-export-with-powershell-part-1-of-2

The import function is called “Import-SPDesignPackage” and here are the details:

Import-SPDesignPackage

Here are some samples

#First sample

Import-SPDesignPackage -SiteUrl "http://sharepoint.local/publishing" -ImportFileName "C:\temp\publishing2.wsp" -PackageName "P2" -Apply $true

#Second sample


(
    @{ SiteUrl ="http://sharepoint.local/sites/publishing1";
       ImportFileName ="C:\temp\publishing1.wsp";
       PackageName ="P1";
       Apply=$true
    },
    @{ SiteUrl ="http://sharepoint.local/sites/publishing2";
       ImportFileName ="C:\temp\publishing2.wsp";
       PackageName ="P2";
       Apply=$true
    }
) | New-ObjectFromHashtable | Import-SPDesignPackage

The first sample shows you how to import one design package to a dedicated site. By using the “Apply” parameter the design package will be applied to the site immediately.

The second sample shows you hot to import two different packages to two different site collections. In the sample I use a hashtable for input parameters. They are assigned to the function parameters by “property name binding”. See “http://technet.microsoft.com/en-us/library/hh847743.aspx”: Section “ValueFromPipelineByPropertyName”:

[…]

For example, if the function has a ComputerName parameter, and the 
piped object has a ComputerName property, the value of the ComputerName
property is assigned to the ComputerName parameter of the function.

The following example declares a ComputerName parameter that is 
mandatory and accepts input from the ComputerName property of the 
object that is passed to the function through the pipeline.

[…]

Some more details about that. Skip it if you are not interested…

<begin/>

This “property name binding” does not work with hashtables. Therefore I created a helper function “New-ObjectFromHashtable” that creates a PowerShell object (“PSObject”). This function is generic. (It’s also included in the script files.)

On the one hand with “new-object System.Management.Automation.PSObject” you can create a new “empty” PowerShell object that can be used in your script as every other object, e.g. a SharePoint object like an instance of class SPSite. With cmdlet “Add-Member” you can add new members to the object. – On the other hand you have a hashtable with named values. You can access the collection of names = keys and with each key you can access the value. – Let’s combine it: You can iterate through the keys collection and create a new member in an empty PSObject instance.
functionNew-ObjectFromHashtable {
    #written by Ingo Karstein (https://blog.kenaro.com)# v1.0#Use this function to convert a hashtable to a PowerShell object ("PSObject"), e.g. for using hashtables for property name binding in# PowerShell pipelines
    [CmdletBinding()]
    param(
        [parameter(Mandatory=$true, Position=1, ValueFromPipeline=$true)]
        [Hashtable]
        $Hashtable
    )

    begin {
        $results= @()
    }

    process {
        $r=new-objectSystem.Management.Automation.PSObject$Hashtable.Keys | % {
            $key=$_$value=$Hashtable[$key]
            $r | Add-Member-MemberTypeNoteProperty-Name$key-Value$value-Force
        }

        $results+=$r
    }

    end {
        $results
    }

}
The resulting object can be passed to each “property name binding” enabled cmdlet. – The PowerShell engine tries to match input object property names and cmdlet parameter names. If there is a match the input object property value gets assigned to the cmdlets input parameter.

The cmdlet can also convert a list of hashtables to a list of objects. That is used in the “Import-SPDesignPackage” script.

<end/>

Parameters

Parameter Name	Parameter Set Name	Mandatory?	Position	Description
SiteUrl	Default	Yes	0	Site Url for import
Site	Site	Yes	0	SPSite object for import
ImportFileName	DefaultSite	Yes	1	Filename and path of the design package for import
Apply	DefaultSite	Yes	2	$true = Apply the design package after import$false = Only install the design package for later activation
PackageName	DefaultSite	No	3	Package name. If not specified it uses the file name without extension. The package name will be used for naming the imported file in the solution gallery of the site collection
MajorVersion	DefaultSite	No	–	Version number of the design package. If not specified it uses “1” for the major version.
MinorVersion	DefaultSite	No	–	Version number of the design package. If not specified it uses “0” for the minor version.

The function returns an object for each processed (or not processed) site collection:

Object Property	Description
SiteUrl	Url of the processed site
Success	$true = Import and “Apply” (if specified) was successful
InputFileFound	$true = File found$false = File not found
InputFileExtensionValid	$true = Input file has extension “.wsp”$false = Input file hat not extension “.wsp”
SiteFound	$true = The specified site was found
SolutionFileName	The name of the solution is auto generated from package name or file name and major and minor version number. This is the name of the package in the site collections solution gallery.
PackageAlreadyExsits	$true = the solution does already exist in the solution gallery.

Some additions

The import process requires the package to be stored inside the site collection before the the last input step. Therefore the function creates a folder named “tmp_importspdesignpackage_15494B80-89A0-44FF-BA6C-208CB6A053D0” in the site collections root web root folder. In this folder the package gets uploaded. From the location the package is imported. The folder will be deleted after successful or not failed import.

SharePoint 2013 Design Packages: Export with PowerShell (Part 1 of 2)

Last night I search for “export import sharepoint 2013 design packages powershell”. No luck there. – So I created two functions for this purpose. It works nicely 🙂

The functions only use public methods of the SharePoint (Server) Object Model. No reflection, et cetera. The most important class in this context is “Microsoft.SharePoint.Publishing.DesignPackage”. It has two methods: Export and Install. This I used to create to PowerShell functions: Export-SPDesignPackage and Import-SPDesignPackage. Both are able to work in PowerShell pipeline context. This gives you the possibility to export a bunch of Design Packages from several sites using PowerShell.

You can download the scripts here:

http://gallery.technet.microsoft.com/Export-and-Import-0f41b376

You can use the scripts as PowerShell modules or by copying the content to your own PowerShell script files. But please be careful: By now it’s only tested in my dev environment!!

The scripts use the SharePoint Server Object Model. So they have to be executed on a SharePoint farm server! You also need an priviledged account that has rights to export (or import) SharePoint Design Packages.

Today I’ll describe the export function. ~~Tomorrow or the day after tomorrow I’ll publish a description of the import function.~~ Here is the import part: https://blog.kenaro.com/2013/02/18/sharepoint-2013-design-packages-import-with-powershell-part-2-of-2/

Export-SPDesignPackage

Here are some samples:

$site1=get-spsite"http://sharepoint.local/publishing" 
$site2=get-spsite"http://sharepoint.local/sites/publishing2"

#First Sample

$cred=new-objectSystem.Management.Automation.PSCredential( "domain\spfarm", (ConvertTo-SecureString-AsPlainText"Passw0rd"-Force))

$site1, $site2 | Export-SPDesignPackage -UseTempFileForExportWithExtension ".wsp" -DownloadCredentials $cred -PackageName "test"#Second Sample

$site1, $site2 | Export-SPDesignPackage -ExportFileName "C:\temp\Package.wsp" -UseExportFileNumbering -IncludeSearchConfig -DisposeSiteObject -OverwriteExistingFiles

#Third Sample

(
    @{PackageName="P1"; ExportFileName="C:\temp\p1.wsp"; SiteUrl="http://sharepoint.local/publishing"},
    @{PackageName="P2"; ExportFileName="C:\temp\p2.wsp"; SiteUrl="http://sharepoint.local/sites/publishing2"}
) | New-ObjectFromHashtable | Export-SPDesignPackage

#Fourth Sample

$site2 | Export-SPDesignPackage -ExportFileName "C:\temp\publishing2.wsp"  -IncludeSearchConfig -DisposeSiteObject -OverwriteExistingFiles

The first sample uses two SPSite objects as (pipeline) input and tells the function to export the design packages to temp files with auto generated names. For the download of the packages from the sites you can specify “download credentials”.

The second sample exports the same two SPSites. The export file name is specified. By using “UseExportFileNumbering” a number is inserted into the file name like this: “c:\temp\package-1.wsp”. So both export packages have different file names.

The third sample exports two sites with individual export settings for each site. This is possible by “parameter binding by property name” where PowerShell binds the input object’s property to the function / cmdlet input parameters by name matching. But this does not work with hashtables. Therefore I created a helper function “New-ObjectFromHashtable” that creates a PowerShell object (“PSObject”). This function is generic. (It’s also included in the script files.)

The fourth sample exports just one site.

Parameters

The function has the following parameters. All can be bound by “parameter binding by property name”!

Parameter Name	Parameter Set Name	Mandatory?	Position	Description
SiteUrl	Default	Yes	0	Url of Site Collection as System.String
Site	Site	Yes	0	SPSite-object
ExportFileName	Default Site	No	1	Name for the exported file in the file system. The folder must exist! Cannot be used together with “ExportFolder” and “UseTempFileForExportWithExtension”!
ExportFolder	Default Site	No	1	Name of the folder for the exported design packages. The file name will be created through the SharePoint Server Object Model. Cannot be used together with “ExportFileName” and “UseTempFileForExportWithExtension”!
UseTempFileForExportWithExtension	Default Site	No	1	When specified the function will create a file name automatically by using "System.IO.Path.GetTempFileName()”. But it adds the extension you specify here. You should use “.wsp” by default.
PackageName	Default Site	No	2	Name of the export package. This is not a file name but an internal name that is used inside the design package. This is optional. The Object Model can handle it for you.
IncludeSearchConfig	Default Site	No	3	http://msdn.microsoft.com/en-us/library/jj862342.aspx
DisposeSiteObject	Site	No	–	If you use SPSite objects as input you can specify whether the function should dispose it or not. Default: TRUE = “Please dispose it for me”!
DownloadCredentials	Default Site	No	–	You can specify credentials for the download of the generated package. The package is stored in the the solution gallery of the site collection. It’s downloaded by the function by using System.Net.WebClient with “DefaultNetworkCredentials” if no credentials are specified.
OverwriteExistingFiles	Default Site	No	–	If specified it overwrites the export file if it exists. If not specified it skips the export. But in the case nevertheless the design package will be created .
UseExportFileNumbering	Default Site	No	–	If you use “ExportFileName” you can specify this parameter to insert numbers into the given file name as described above.

The function returns an object for each processed (or not processed) site collection:

This objects can be used in pipelines or … as you like.

Object Property	Description
Site Url	Url of the processed site
Success	TRUE = Export successful, export file created.
SiteFound	The site collection was found
ExportError	$null = OK System.Exception = Error occurred
PackageFileName	Name of the Package created by the Object Model
PackageName	Name of the Package created by you OR the Object Model
PackageMajorVersion	…created by Object Model during export
PackageMinorVersion	…created by Object Model during export
ExportFileOverridden	If “TRUE” the export file did exist but was overridden during export. If “OverwriteExistingFiles” parameter was NOT specified this property will always be FALSE.
DownloadError	$null = OK System.Exception = Error during download

Some Additions

The design package will be stored in the solution gallery of the site collection that can be found here: <site-collection-url>/_catalogs/solutions. It’s the same location as for the sandboxed solutions. It interesting: sandboxed solutions are deprecated but in this case they use at least the same storage for a new functionality.

After the package is created you can download it from the solution gallery. No big deal.

Gimmick: Write To SharePoint Log using PowerShell functions

In preparation for a deployment project I wrote some PowerShell functions to write messages to the SharePoint ULS.

You can download the PowerShell script here: http://gallery.technet.microsoft.com/Write-Messages-to-b59565bf

There are some samples in the package.

This is what it looks like in ULSViewer:

Red = Area or “Product” in ULSViewer

Green = Category

Blue = Severity Level

Purple = Message

You can use the script file “SPLogging.ps1” as PowerShell module. In the following sample the SPLogging.ps1 file is stored in the same location as “SPLoggingDemo.ps1”. Or you copy the content of “SPLogging.ps1” to your own file.

Import-Module "$(split-path $MyInvocation.MyCommand.Path)\SPLogging.ps1"

Here are some samples about how to create “Areas”

Add-SPDiagnostigLoggingArea -AreaName "TestArea"

"PowerShell", "PS1", "PS2" | Add-SPDiagnostigLoggingArea

This is how you create categories:

Add-SPDiagnostigLoggingAreaCategory -AreaName "TestArea" -CategoryName "Category1" -TraceSeverityDefault High

Add-SPDiagnostigLoggingAreaCategory "TestArea\Category2" -TraceSeverityDefault High

"Test1", "Test2", "Test3" | Add-SPDiagnostigLoggingAreaCategory -AreaName "PowerShell" 
"Test1", "Test2", "Test3" | Add-SPDiagnostigLoggingAreaCategory -AreaName "PS1"

You can add new categories by specifiying the area and the new category name seperatly or as formatted string: <area><backslash><category>

The following snipped shows you how to query the areas and categories you created in your PowerShell session.

Get-SPDiagnosticLoggingCategory -CategoryName "PowerShell\Test1"

Get-SPDiagnosticLoggingCategory -AreaName "PowerShell"

Get-SPDiagnosticLoggingCategory

You have only access to your own areas and categories!!

Finally here are some examples of how to write messages to the SharePoint ULS. You can use PowerShell pipelining!

Write-SPDiagnosticLogging -CategoryName "PowerShell\Test1" -Message "Hello 1!" 

"Hello 2!" | Write-SPDiagnosticLogging -CategoryName "PowerShell\Test1" 

"Hello 3!", "Current date/time: {0}" | Write-SPDiagnosticLogging -CategoryName "PowerShell\Test2" -MessageArguments @(([DateTime]::Now)) -TraceSeverity "High"

Writing to the Windows Event Log is not supported at this moment.