Snowflake Demo Project
CYCL has implemented a demo project that showcases the basic implementation of a Snowflake. The goal is to provide MatchPoint Snowflake implementers with a starting point when implementing a custom Snowflake.
This chapter describes how the demo project is organized and highlights important factors.
Please note that it is highly recommended to change GUIDs and identifiers to new unique values in case you use the demo project as a template for your own Snowflake. There will be errors, if multiple Snowflakes use the same identifiers.
Basic Structure
The demo project is a regular Visual Studio project for SharePoint 2019, which can be packaged and deployed to SharePoint as a WSP solution.
The project structure contains following folders:
| Folder name | Description and contents |
|---|---|
| Features |
The features folder contains two features:
|
| Package | The package folder defines the content of the SharePoint Solution (WSP) |
| Images | The images folder is a SharePoint-mapped folder and stores all image files used by this Snowflake. |
| Layouts | The layouts folder is a SharePoint-mapped folder and contains User Controls, JavaScript and CSS files used by this Snowflake. |
| ListInstances | This folder contains a "Site Pages" list instance with a SitePagesModule. This module defines the pages which are relevant for the Snowflake. Web parts can be added to the pages within the elements file. In this demo project, one page is created (Default.aspx) with three Web Parts on it. |
| Modules | The modules folder contains a ConfigurationFiles module that contains all MatchPoint configuration files required by this Snowflake. Each configuration type has its own folder, according to the structure defined for the "MatchPoint Configuration" document library. |
| Src | This folder contains the class files with the custom code. |
Custom MatchPoint Snowflake Configuration Class
Each MatchPoint Snowflake within MatchPoint Snow needs to have its own
configuration file in the "MatchPoint Configuration" document library.
Either a MatchPoint Snowflake uses an instance of the
SnowflakeConfiguration or it implements its own configuration class.
Using an own configuration class is recommended if the MatchPoint Snowflake Configuration needs to define additional parameters used within the Snowflake.
The demo project implements a DemoSnowflakeConfiguration class that
inherits from CustomSnowflakeConfiguration. The configuration class
implements ISingletonConfiguration in order to ensure a singleton
configuration (i.e. only one instance of the MatchPoint Snowflake /
configuration can be created per MatchPoint instance.) In most use cases
implementing ISingletonConfiguration is recommended.
Whenever an own configuration class for a Snowflake is implemented a license key for the Snowflake is required. The Licensing of a Snowflake is described in detail in Licensing.
Features and Event Receivers
Snowflake
The MatchPoint Snowflake feature contains all elements of the demo project, with the exception of the MatchPoint configuration files. This feature needs to be activated on the base site collection of the Snowflake.
The MatchPoint Snowflake configuration file has to be configured with the URL of this site collection in order for MatchPoint Snow to be able to display it under the Snowflakes node in the top navigation.
The Snowflake.EventReceiver.cs class extends the generic class
SnowflakeFeatureReceiver. The generic type parameter T needs to be
an implementation of the BaseSnowflakeConfiguration class and the
configuration class related to this Snowflake.
The SnowflakeFeatureReceiver provides an abstract method
GetSnowflakeConfigurationFilename. This method has to be implemented
and must return the name of the associated MatchPoint Snowflake
configuration file. MatchPoint Snow then automatically stores the site
collection URL in the SiteCollectionUrl property of the
SnowflakeConfiguration with the specified name.
Please note that in case your custom snowflake configuration doesn't implement ISingletonConfiguration, meaning multiple instances of the configuration can be available, the GetSnowflakeConfigurationFilename method of the event receiver must return null. MatchPoint Snow then knows that there is more than one configuration file and will not update it. The SiteCollectionUrl must then be set manually.
SnowflakeConfiguration
All MatchPoint configuration files required by the demo project are
placed in a module named ConfigurationFiles. The folder structure
within this module must correspond with the structure used within the
MatchPoint configuration document library.
This module is added to the SnowflakeConfigurations feature and
automatically deployed to SharePoint. For more details on how this is
done, please visit following link:
Configuration Files
The demo project deploys the following configuration files:
Acme.DemoSnowflake.HelloWorld.xml: a Composite Configuration which prints hello world.DemoSnowflakeConfiguration.xml: The configuration file (singleton) for the SnowflakeDemoSnowflake.StringResources.xml:The additional String Resources for the demo Snowflake
Additional information
The demo project contains a \_script folder. This folder contains a
PowerShell script named Activate-Features.ps1. This is executed as a
PostDeploymentCommand by MSBuild (see
Colygon.MatchPoint.DemoSnowflake.csproj for more details).
The script activates the features on the MatchPoint Snowflake site and on the MatchPoint instance administration site. The URL are passed via parameter and need to be specified within the csproj.user file:
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<SharePointSiteUrl>http://hostname/sites/demosnowflake/</SharePointSiteUrl>
<MatchPointInstanceUrl>http://hostname/</MatchPointInstanceUrl>
</PropertyGroup>
</Project>
In case you do not have a .user file, you can create one by specifying
the Site URL property within the project properties.
If you want to provide an installer with your Snowflake, you need to activate all features according to this script.