SharePoint.DesignFactory.ContentFiles

Welcome to the landing page of the SharePoint.DesignFactory.ContentFiles NuGet package.

Please see the following blog posts:

Documentation SharePoint.DesignFactory.ContentFiles

About

The DesignFactory.SharePoint.ContentFiles mechanism is designed for deploying SharePoint files with optional meta data to a SharePoint environment. This SharePoint environment can be:

  • a local environment, running on the same machine as where you are developing or deploying your content files
  • a remote environment, running on either the same machine or a machine that is accessible remotely over http.

In both scenario's the files will end up in the SharePoint content database, as if they were uploaded by hand. This means that files are deployed in another way than if they were deployed using a WSP package using features and modules. Files are deployed as customized files. See Understanding and Creating Customized and Uncustomized Files in Windows SharePoint Services 3.0 for a good article on customized and uncustomized files.

Project structure

A SharePoint.DesignFactory.ContentFiles project has the following strucure:

  • ProjectFolder
    • _MachineConfiguration - configuration files describing connections to SharePoint web (SPWeb)
      • Default.ps1 - configuration file used if there is no specific configuration file for the currenty machine (MACHINE.ps1)
      • Machine1.ps1 - machine specific configuration file
      • Machine2.ps1 - machine specific configuration file
      • SPDesign.ps1 - configuration file for SharePoint web to be used for importing artifacts in project folder if no specific configuration file to use for import is specified [not used yet]
    • _Tools
      • Deploy.cmd - command for deploying all changed files in project
      • Redeploy.cmd - command for deploying all files in project
      • Package.cmd - command for packaging the files in the project
      • Clean.cmd - command to mark all files in the project for redeployment
      • SharePoint.DesignFactory.ContentFiles.ps1 - the script implementing all functionality. Can be called directly as well for more advanced features
      • ContextExtensions... - folder containing extension functions that can be used in ObjectModel and ClientObjectModel
      • Documentation... - folder containing documentation
      • Lib... - folder containing a library of reuseable functions
      • MSBuild... - folder containing a SharePoint.DesignFactory.ContentFiles specific MSBuild targets file
    • MasterPages - A folder mapped in Mappings.xml for deployment to SharePoint
      • MyMaster.master - file to be deployed to SharePoint
      • MyMaster.master.properties.ps1 - metadata for the file to be deployed to SharePoint
      • ...
    • PageLayouts
      • ...
    • ...

Some remarks on the above project structure:

  • The project structure can be used from any tool that is your favorite HTML editor, like:
    • Visual Studio 2010 (lower versions are supported, but not through nuget package installation)
    • WebMatrix 2.0 (still in beta, does support nuget package installation)
    • ... enter your vaforite web editor here ...
  • Visual Studio 2010 has many enhancements for working with SharePoint.DesignFactory.ContentFiles

Mappings.xml

The Mappings.xml file describes a relationship between the project folder and where artifacts in the project folder should be deployed in to SharePoint. The Mappings.xml file looks like:

<ContentFilesMappings xmlns="http://solutionsfactory.macaw.nl/ContentFilesMappings-1.0">
    <Mappings>
        <Mapping projectFolder="RootFolder" destinationFolder="/" />
        <Mapping projectFolder="Documents" destinationFolder="/documents" />
        <Mapping projectFolder="Masterpages" destinationFolder="/_catalogs/masterpage" />
        <Mapping projectFolder="PageLayouts" destinationFolder="/_catalogs/masterpage" />
        <Mapping projectFolder="Style Library" destinationFolder="/Style Library" />
    </Mappings>
</ContentFilesMappings>

A Mapping node describes the mapping from a project folder to a SharePoint folder.

The Mapping node attribute projectFolder':

  • refers to a folder within the project
  • must be specified
  • may not be empty
  • may not point to the root folder of the project, only files from subfolders can be uploaded

ProjectFolders for multiple Mapping elements must be disjunct; e.g. valid is:

<Mapping projectFolder="sub1" ... >
<Mapping projectFolder="sub2" ... >

invalid is:

<Mapping projectFolder="sub1" ... >
<Mapping projectFolder="sub1\sub3" ... >

The Mapping node attribute destinationFolder:

  • specifies a folder within SharePoint relative to the SharePointWebUrl as specified in the machine configuration file
  • must be specified
  • may not be empty
  • to specify the root folder in 'SharePointWebUrl' specify '/'

If the destination folder does not exist yet it will be created as an SPFolder. Any child folders below the projectFolder will result in corresponding child urls (SPFolders) in the destination folder.

Working with the command-line tools

The following command-line tools are available for performing the simple tasks involved in working with SharePoint.DesignFactory.ContentFiles:

  • _Tools\deploy [machineconfigurationname] - deploy changed files in the project using configuration MACHINE.ps1, Default.ps1 or specified configuration
  • _Tools\redeploy [machineconfigurationname] - deploy all files in the project using configuration MACHINE.ps1, Default.ps1 or specified configuration
  • _Tools\package - package all files in the project
  • _Tools\clean - mark all files in the project for redeployment

For more advanced actions like deploying or marking for deployment a single file or folder the underlying PowerShell script _Tools\SharePoint.DesignFactory.ContentFiles.ps1 can be used. To see the available parameters open a PowerShell command prompt in the project foder and execute the following command:

get-help _Tools\SharePoint.DesignFactory.ContentFiles.ps1

Open this script file for more details on the available arguments.

Visual Studio 2010 integration

There is extensive integration with the Visual Studio 2010 IDE if SharePoint.DesignFactory.ContentFiles is installed as a NuGet package:

  • Create a new ASP.NET 3.5 Web Application project - File -> New -> Project..; Select .NET Framework 3.5; Select template Visual C# -> Web -> ASP.NET Web Application
  • Ensure that the Macaw NuGet repository is accessible:
    • Open Tools -> Library Package Manager -> Package Manager Settings
    • Go to Package Manager -> Package Source
    • Add source: Name = Macaw NuGet, Source = http://nuget.macaw.nl/nuget
  • Add the SharePoint.DesignFactory.ContentFiles NuGet package to the project and solution:
    • Open Tools -> Library Package Manager -> Manage NuGet Packages for Solution...
    • Select Online and the source Macaw NuGet
    • Now select the SharePoint.DesignFactory.ContentFiles package and hit Install. Add the package at both the project and solution level.

Right click menus

The SharePoint.DesignFactory.ContentFiles NuGet package adds right click menu entries if the Managed Menu Extension (MME) is installed. These extension can be installed through the Visual Studio 2010 UI:

  1. Open Tools -> Extension Manager..
  2. Select Online
  3. Search for managed Menu Extension (MME)
  4. Select managed Menu Extension (MME) and hit Install

Close and reopen the Visual Studio 2010 instance containing your project to get the right click menu's loaded.

The following right click actions are now added:

On SharePoint.DesignFactory.ContentFiles project:

  • DesignFactory -> Deploy changed files
  • DesignFactory -> Deploy all files
  • DesignFactory -> Mark all files for deploy
  • DesignFactory -> Package
  • DesignFactory -> Documentation ContentFiles

On mapped folder (folder in project mapped to SharePoint folder with Mappings.xml):

  • DesignFactory -> Deploy changed files in folder
  • DesignFactory -> Deploy all files in folder
  • DesignFactory -> Mark folder for deploy
  • DesignFactory -> Documentation ContentFiles

On mapped file (file in folder in project that is mapped to SharePoint folder with Mappings.xml): - DesignFactory -> Deploy file - DesignFactory -> Deploy all files in folder - DesignFactory -> Mark file for deploy - DesignFactory -> Documentation ContentFiles

Configurations

The SharePoint.DesignFactory.ContentFiles NuGet package adds the following configurations to the project and to the solution, besides the Debug and Release configurations:

  • Deploy: build project in Debug mode, and deploy changed content files
  • Redeploy: build project in Debug mode, and deploy all content files
  • Package: build project in Release mode, and build package

The following action is also supported when you right-click on a project:

  • Clean: marks all files in the project for redeployment, default project clean action is executed

Select a configuration and build the project/solution. The configurations correspond with the command-line commands.

It is also possible to add additional configurations using the Visual Studio Configuration dropdown, with at the end Configuration Manager.... In this way the following additional deployment commands can be added:

  • Deploy machineconfigurationname, i.e. Deploy Office365
  • Redeploy machineconfigurationname, i.e. Redeploy Office365

Note that a solution configuration builds projects with a specific configuration. This works fine after installation of the NuGet package. If the SharePoint.DesignFactory.ContentFiles package is uninstalled and installed again, the solution configurations are not aligned anymore to the project configurations. To align again open the Configuration dropdown, and select at the end Configuration Manager.... Now align solution configurations with project configurations.

Machine configuration files

A machine configuration file is used to describe how to deploy the current project to SharePoint. The machine configuration file describes a deployment to a local machine (SP2007/SP2010) or a remote machine (SP2010). Deployment to the local machine can be done using the ObjectModel or the ClientObjectModel. Deployment to a remote machine is done with the ClientObjectModel. A machine configuration file is:

  • Located in the folder MachineConfiguration in the project folder
  • Named after the machine name, i.e. MYMACHINE.ps1 for the default deployment (Deploy.cmd, Redeploy.cmd) OR
  • Named as wanted. Requires explicit deployment, i.e. Deploy NAME, Redeploy NAME.
  • The machine configuration file Default.ps1 will be used for deployment if no machine specific configuration file exists
  • TODO: The machine configuration file SPDesign.ps1 will be used for importing SharePoint artifacts if no explicit configuration file is specified

This machine configuration file is executed as a PowerShell script and returns a Hashtable with the following keys:

  • SharePointDeployment - MANDATORY
    • ObjectModel (on server itself, SP2007/SP2010)
    • ClientObjectModel (remote, SP2010)

If ObjectModel is used for deployment, sharepoint is accessed with the credentials of the current user (integrated security).

  • SharePointWebUrl - MANDATORY
    • Example: 'http://myserver/sites/mysitecollection'

Url to the SharePoint web site where the content files must be deployed to. In most cases this is the root site of a site collection, but it can be any SharePoint site. The content files in the package can only be deployed to locations within the specified site.

  • UserName - OPTIONAL
    • 'DOMAIN\UserName'

User name to authenticate with. Must be in the format DOMAIN\UserName. If not specified check if the credentials to authenticate for the SharePointWebUrl are specified in the Windows Credential Manager.

  • Password - OPTIONAL
    • 'MyPassword'

Password to authenticate with.

  • UseClaims - OPTIONAL
    • $true or $false

Boolean that specifies if authentication should be done using claims authentication. This is for example the case for Office365. Note that claims-based authentication for now only works with SharePointDeployment set to ClientObjectModel.

Authentication is done as follows:

  1. If SharePointDeployment is set to ObjectModel
    • Always use integrated security (credentials of currently logged in user)
  2. If SharePointDeployment is set to ClientObjectModel
    • If UserName,Password is specified and not empty, use these
    • Otherwise use the credentials specified in the Windows Credential Manager for Url SharePointWebUrl
  3. If no credentials found --> error.

Using these key,value pairs multiple authentication approaches can be taken:

Integrated security:

@{
    SharePointDeployment = 'ObjectModel';
    SharePointWebUrl = 'http://myserver/sites/mysitecollection';
    UserName = '';
    Password = '';
    UseClaims = $false;
}

Integrated security (as short as possible):

@{
    SharePointDeployment = 'ObjectModel';
    SharePointWebUrl = 'http://myserver/sites/mysitecollection';
}

Explicit authentication (ClientObjectModel deployment only):

@{
    SharePointDeployment = 'ClientObjectModel';
    SharePointWebUrl = 'http://myserver/sites/mysitecollection';
    UserName = 'DOMAIN\UserName';
    Password = 'Password';
    UseClaims = $false;
}

Explicit authentication (ClientObjectModel deployment only), but user name and password configured in Windows Credential Manager:

@{
    SharePointDeployment = 'ClientObjectModel';
    SharePointWebUrl = 'http://myserver/sites/mysitecollection';
    UseClaims = $false;
}

Explicit claims-based authentication (ClientObjectModel deployment only):

@{
    SharePointDeployment = 'ClientObjectModel';
    SharePointWebUrl = 'http://myserver/sites/mysitecollection';
    UserName = 'DOMAIN\UserName';
    Password = 'Password';
    UseClaims = $true;
}

Explicit claims-based authentication (ClientObjectModel deployment only), but user name and password configured in Windows Credential Manager:

@{
    SharePointDeployment = 'ObjectModel';
    SharePointWebUrl = 'http://myserver/sites/mysitecollection';
    UseClaims = $true;
}

How files are marked for deployment

The Archive atribute is used to mark files for deployment. if the Archive attribute is set, the file must be deployed. After a file is successfully deployed the Archive attribute is cleared. The Archive attribute can also be set on read-only files.

There is a case where the Archive attribute is fooled. If a file that is under TFS source control is reverted to an older version, the file should be deployed again. On Revert the Archive attribute is not set, so the file will not be deployed, although it has been updated (to an older version).

In case of reverting from TFS source control, mark the specific file or folder for deployment.

NuGet package installation

When the NuGet package is installed in Visual studio the following actions are performed:

  • Add the configurations Deploy, Redeploy and Package to the project and to the solution
  • Add import of targets file SharePoint.DesignFactory.ContentFiles.targets in the project file to provide handling of building the configurations Deploy, Redeploy and Package, and a target Package for automating packaging
  • Remove the folders App_Data, Scripts and Default.aspx from the project if it is a web project
  • Copy assembly VSMenuManager.SharePoint.DesignFactory.ContentFiles.dll to the solution folder for right click menu extensions (requires restart of Visual Studio to be picked up)

This tool is copyright 2012, Macaw.

1 Comment

Comments have been disabled for this content.