202 lines
9.5 KiB
Plaintext
202 lines
9.5 KiB
Plaintext
PowerShellHostClassifier Project
|
|
|
|
Demonstrates
|
|
This is an introduction to the extensibility model for FSRM Classification.
|
|
It demonstrates how to develop a custom managed classifier that will be a part of the FSRM pipeline and
|
|
use a powershell script per rule to classifiy files. See "How to write the script:" on the structure of the script
|
|
|
|
Languages
|
|
This sample is available in the following language implementation:
|
|
C#
|
|
hosted scripts are in powershell
|
|
|
|
Files
|
|
|
|
PowerShellHostClassifier.csproj
|
|
This is the main project file for VC# projects generated using an Application Wizard.
|
|
It contains information about the version of Visual C# that generated the file, and
|
|
information about the platforms, configurations, and project features selected with the
|
|
Application Wizard.
|
|
|
|
PowerShellHostClassifier.cs
|
|
This contains the class that implements the IFsrmClassifierModuleImplementation interface
|
|
enabling this classifier to become a part of the FSRM classification pipeline and load a powershell
|
|
script for each file.
|
|
|
|
PowerShellRuleHoster.cs
|
|
This class abstracts the rule, and hosts the powershell pipeline allowing classification using a script.
|
|
|
|
BlockablePropertyBagEumerator.cs
|
|
This class contains an IEnumerator implementation and allows for putting propertyBags into powershell
|
|
and finding out when powershell has finished consuming the current propertyBag
|
|
|
|
OverloadStream.cs
|
|
This is a Stream implementation that wrapps IStream. This is useful because IStream isn't very useful in managedcode / powershell.
|
|
|
|
ModuleSuppressions.cs
|
|
This file contains all compile time warnings suppressions for FXCOP.
|
|
|
|
keyfile.snk
|
|
A key to strong name sign the dll
|
|
|
|
classreg2.reg
|
|
Registry settings to enable classifier registration
|
|
|
|
eventlog.reg
|
|
Registry settings for creating the eventlog
|
|
|
|
powershell_scripts\content_classifier.ps1
|
|
An example powershell script that shows how to parse rule additional parameters and classify based on file content
|
|
This runs in Classifier Supplied Value mode
|
|
|
|
powershell_scripts\demo_script.ps1
|
|
A very minimal example powershell script that simply classifies .txt files as their filename minus .txt
|
|
This runs in Classifier Supplied Value mode
|
|
Powershell_scripts\yes_no_script.ps1
|
|
A very minimal exmaple powershell script that classifies .txt files to the set value
|
|
This runs in yes/no classifier mode
|
|
|
|
install_as_external.cmd/register_fsrm_module.vbs/register_with_fsrm_as_external.vbs
|
|
These scripts register the dlls, register with COM+ (for debugging ease) and register with FSRM respectively.
|
|
For ease of debugging, the script registers the server as external and the process running the classifier
|
|
can be identified as the service with name of the classifier, PowerShellHostClassifier.
|
|
|
|
install_as_network_service.cmd/RegisterWithFsrmAsNetworkService.vbs
|
|
These scripts register the dlls and register with FSRM respectively.
|
|
The script registers the server to run under network service account and during classification the server runs
|
|
under network service account in a dllhost.exe process. This method of installation eliminates the extra layer of COM+
|
|
registration but it is tougher to debug owing to the reason that a debugger cannot be attached during DLL load since to
|
|
identify the dllhost.exe hosting the server when classification runs requires looking for the dllhost.exe
|
|
process (among the many potentially running on the machine) which has loaded the sample DLL, namely PowerShellHostClassifier.dll.
|
|
|
|
Prerequisites
|
|
|
|
Windows Server 2008 R2
|
|
|
|
Building the Sample
|
|
|
|
To build the sample using the command prompt:
|
|
=============================================
|
|
1. Open the Command Prompt window and navigate to the directory.
|
|
2. Type msbuild PowerShellHostClassifier.sln
|
|
|
|
[NOTE: PowerShellHostClassifier.sln has an assembly reference to "C:\Program Files\Reference Assemblies\Microsoft\FSRM\v7.0\srmlib.dll" as the default path assuming the SDK was installed into "C:\Program Files\" and its references imported for Visual Studio (using Windows SDK COnfiguration tool). If the SDK was installed elsewhere, please point to the correct srmlib.dll for the build to succeed]
|
|
|
|
|
|
|
|
To build the sample using Visual Studio 2005 (preferred method):
|
|
================================================
|
|
1. Double-click the icon for the PowerShellHostClassifier.sln (solution) file to open the file in Visual Studio.
|
|
2. In the Build menu, select Build Solution. The application will be built in the default \Debug or \Release directory.
|
|
|
|
[NOTE: PowerShellHostClassifier.sln has an assembly reference to "C:\Program Files\Reference Assemblies\Microsoft\FSRM\v7.0\srmlib.dll" as the default path assuming the SDK was installed into "C:\Program Files\" and its references imported for Visual Studio (using Windows SDK COnfiguration tool). If the SDK was installed elsewhere, please point to the correct srmlib.dll for the build to succeed]
|
|
|
|
Installing the Sample
|
|
=====================
|
|
|
|
This sample provides 2 methods to install the sample:
|
|
|
|
Method 1:
|
|
---------
|
|
|
|
Run the attached install_as_external.cmd script.
|
|
|
|
This script will need to be edited if any changes to the classifier or its hosting model is required.
|
|
This does the following:
|
|
Installs the binaries to %systemdrive%\PowerShellHostClassifier
|
|
regsvr32 /s PowerShellHostClassifier.dll
|
|
register_fsrm_module.vbs registers with COM+
|
|
register_with_fsrm_as_external.vbs registers this classifier with the FSRM pipeline
|
|
|
|
Method 2:
|
|
---------
|
|
|
|
Run the attached install_as_network_service.cmd script.
|
|
|
|
This script will need to be edited if any changes to the classifier or its hosting model is required.
|
|
This does the following:
|
|
Installs the binaries to %systemdrive%\PowerShellHostClassifier
|
|
regsvr32 /s PowerShellHostClassifier.dll
|
|
register_with_fsrm_as_external.vbs registers this classifier with the FSRM pipeline
|
|
|
|
As mentioned above, Method 1 is easier to debug since the classifier (server) can be identified as the windows service with name of the classifier,
|
|
PowerShellHostClassifier while Method 2 runs the server under a dllhost.exe process. But Method 2 eliminates the additional layer of complexity
|
|
involved with COM+ and COM+ registration which Method 1 requires.
|
|
|
|
Modes of install:
|
|
================
|
|
The classifier can be installed in Classifier Supplied Value mode(NeedsExplicitValue = false) and yes no mode (NeedsExplicitValue = true)
|
|
The default scripts install the Classifier in Classifier Supplied Value mode. To change it either change the module paramter to NeedsExplicitValue to true
|
|
Or install another instance with a different name and the NeedsExplicitValue module parameters as true (by editing the .vbs scripts used in the install)
|
|
|
|
|
|
|
|
Running the Sample
|
|
|
|
To run the sample:
|
|
=================
|
|
1. Run File Server Resource Manager (FSRM.msc)
|
|
2. Go to Classification Management -> Classification Properties
|
|
3. Define a custom property
|
|
4. Go to Classification Rules
|
|
5. Create a new rule, provide rule name, scope, and on Classification Tab select 'Powershell Host Classifier' in classification mechanism.
|
|
5.1 click Advanced and ensure that the additional parameters has the Name filed populated with the string "ScriptFileName" and the Value field is populated with the "actual path to the powershell script file". Details of writing script are below.
|
|
6. Create several files in the scope directory
|
|
7. Run classification
|
|
8. Notice that the files will get classified appropriatelly
|
|
|
|
|
|
|
|
|
|
|
|
How to write the script:
|
|
|
|
|
|
Structure:
|
|
=========
|
|
To create a script you need to create a text that contains minimally a process block, and optionally a begin and end block.
|
|
Do not contain any other blocks. Functions can be declared inside the begin block.
|
|
Samples are provided inside the powershell_scripts\ folder
|
|
|
|
Yes/No Mode:
|
|
===========
|
|
In Yes/No mode inside the process block, for each property bag emit $true if you want the value to be applied, $false or nothing if you don't
|
|
|
|
|
|
Classifier Supplied Value mode:
|
|
==============================
|
|
In Classifier Supplied Value mode inside the process block, for each property bag if you want the property updated emit the correct object, otherwise emit no object
|
|
|
|
Bool - a boolean object either $true or $false
|
|
|
|
Number - an integer
|
|
|
|
string - a string
|
|
|
|
orderedlist - a string
|
|
|
|
multichoice - a string composed of values optionally concatenated by pipe ex1: "value1" ex2: "value1|value2|value3"
|
|
|
|
multistring - a string composed of multiple strings concatenated by pipe ex1: "some random string" ex2: "anystring|some other random string|the number 5"
|
|
|
|
date-time - a datetime object
|
|
|
|
|
|
Pipeline Input:
|
|
==============
|
|
In the process block the pipeline input will be an IFsrmPropertyBag with an additional method called .GetStream()
|
|
this Method returns a Stream instead of an IStream which is much more usefull in powershell
|
|
powershell_scripts\content_classifier.ps1 shows an example of this additional function being called
|
|
|
|
|
|
Additional Input:
|
|
================
|
|
Other parameters that are passed into the script that are just globally acessable are the following
|
|
|
|
$Rule - an IFsrmClassificationRule that contains the definition of the rule that the script is part of
|
|
|
|
$ModuleDefinition - an IFsrmPipelineModuleDefinition that contains the definition of the moduledefinition
|
|
|
|
$PropertyDefinition - an IFsrmPropertyDefinition that states the definition of the property that is being optionally set
|
|
|
|
$PropertyBagList - Do not override this global object it is being used to control input into the pipeline |