SnAdmin

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 100%
  • 6.3.1
  • Enterprise
  • Community
  • Planned

Overview

SnAdmin
Sense/Net ECMS is a web application but it is a lot more complex than a simple web CMS. Patching, upgrading or executing batch operations on the core product (or a custom solution built on it) is one of the most important tasks of developers and operators. This article introduces SnAdmin that will be the one and only tool that operators will use for these tasks in Sense/Net. From version 6.3.1 you can use this tool to execute patches, perform upgrades or simply import a few content. It can be considered as a framework also that is extendible by third party developers to perform custom tasks.

From version 6.5.5 SnAdmin also offers a growing number of built-in tools that will let you perform common operations like importing content items.

What is a package?

The SnAdmin tool is a console application that executes a package. A package is a zip file that encapsulates operations and data. Portal builders and developers create these packages containing all the content and executables for a feature or a bugfix. The package can be executed on test servers first, minimizing the chance of installation errors in production environment.

SnAdmin checks prerequisites, executes all the steps (similar to workflow activities) defined in the package, registers the package and handles product and application versions. There are a couple of built-in steps in the system, the workflow is highly customizable and developers can write custom install steps in a few minutes.

The following list contains what a package can do.

  • import or export content
  • add or update libraries (e.g. in the web folder)
  • copy or delete files in the file system
  • execute SQL scripts
  • execute custom code to perform any filesystem or content repository operation

SnAdmin and Sense/Net instance

During package execution the web application must be stopped because SnAdmin may modify the file structure under the web folder, may change the assembly set or execute database scripts (with schema modification).

The package execution process can also use Content Repository services: SnAdmin can start and stop the Content Repository one or more times during the install process and the steps can manage content freely. In this case the SnAdmin tool is the host process.

There is no way to undo a faulty execution so creating a backup is a must. To prevent execution errors in production environment, testing the package on test servers is also recommended.

The Sense/Net web application must be stopped on every web server in the NLBS. Creating a backup of the database, the web folder and Lucene index is strongly recommended.

As you can see below in the configuration section, when working in an NLBS environment, you will need to provide all the network paths to the SnAdmin tool. This is necessary to keep all web applications consistent: every operation defined in the package that manages file system entries (e.g. a copy or delete) will be executed on all of the web applications (at least in case of the built-in steps).

Importing without stopping web applications

There is one exception from the best practice stated above, when you may execute SnAdmin without stopping all the web applications in the NLBS. To work like that, your environment will need to fulfill all the following requirements:

  • the package can only contain content to import. No file system or SQL changes are allowed.
  • MSMQ is properly configured in the SnAdmin tool
  • the web application which is on the same machine as SnAdmin still must be stopped, if they use the same Lucene index.
  • you may leave all other web applications running

The package

In this section you can learn about the package itself and how to construct one.

Package type

A package type can be one of the following:

  • Product: a package developed by the Sense/Net product team and modifies the core system (assemblies, configurations, content in the repository, etc.). Such packages do not contain application identifier.
  • Application: a package related to a specific application (a custom project built on Sense/Net). These packages must always contain a unique application identifier given by the application developer.

Package level

The package level can be one of the following:

  • Install: An application's first package must be an 'install' package. This is the package that injects a new application into the system. Only Application packages can be set on this level. An install level package must contain a new application identifier that is unknown to the system. Packages on this level can be executed only once.
  • Patch: Contains small modifications (e.g. a couple of new content to import or a bugfix in a dll). Usually patches form a chain where every package assumes the existence of all the previous ones but it is not mandatory. It is possible to control this behavior, see version control below.
  • ServicePack: May contain bigger modifications or the aggregation of multiple patches.
  • Upgrade: The biggest modification category. After executing this package the application may break the compatibility with older versions.
  • Tool: Can contain small repeatable activities that do not perform significant changes but can be important because of business or technical reasons. A good example is performing an undo checkout on multiple content. Executing a package of this level does not change the application's or the product's version number but the execution is logged and registered.

The definitions of the Patch, ServicePack and Upgrade levels are our recommendations and there is no specific validation related to their level.

Versioning

One of the most important features of this packaging infrastructure is version tracking. Both Sense/Net and application packages will be the subject of prerequisite checking:

  • Version numbers in subsequent packages must be greater than in preceeding ones.
  • If the current official version does not match the expected version provided in the package, the package will not be executed.

Application versioning is the application developer's responsibility. It is strongly recommended to follow this pattern:

  • The revision number (last part of the version) is the changeset id or something similar that can be linked to the source code change.
  • Recommended version increases in the next package, if the package is built based on the changeset 2222:
    • Patch: increase the build number: 1.5.6.1111 --> 1.5.7.2222
    • ServicePack: increase the minor number and reset the build number: 1.5.6.1111 --> 1.6.0.2222
    • Upgrade: increase the major number and reset the others: 1.5.6.1111 --> 2.0.0.2222

You can check the current version information of the core product and all the installed applications using the following OData function:

Package contents

A package is a zip file thats behavior and contents is described by a single manifest file in the package root. It is an XML file containing the metadata for executing the package, as described below. All other material in the package (e.g. dlls and content files) should be in subfolders.

The manifest

This file is required in every package. It contains all metadata and description of the activities (steps). There is no restriction on the name of the manifest file, but we recommend a name that describes the purpose (e.g. 'package.xml' or 'package.manifest'). The manifest is an XML file. There is no explicit schema definition for this file but SnAdmin performs many semantic checks before executing the steps. The manifest has two main sections under the document element (called 'Package'):

  • metadata: a number of XML nodes defining the package
  • Steps: a list of steps to execute
Sample manifest

Metadata

In the metadata section there are required and optional, independent and interrelated parts. Let's look at the details.

  • Package: root node with the following attributes:
    • type attribute (line 2) (required, case insensitive): determines the package type that can be one of the following:
      • Product: developed and distributed by the Sense/Net ECMS product team.
      • Application: a package for custom solutions.
    • level attribute (line 2) (required): the value can be one of the following:
      • Install: in this case the package type must be Application. It checks whether the application exists and registers it.
      • Patch, ServicePack or Upgrade: these packages always increase the application version.
      • Tool: does not raise the version so it can be executed more than once.
  • AppId element (line 3) (required in case of Application packages): the value of this identifier must be unique so the recommended value is a GUID, but it can be a fully qualified name also. See a good namespace convention on MSDN: <Company>.(<Product>|<Technology>)[.<Feature>][.<Subnamespace>]). It is the package builder's responsibility to make sure of the uniqueness of the application identifier.
  • Name element (line 4) (required): cannot be empty. This is the human readable name of the package. Our recommendation is to use the official name of the application in the 'install' level package.
  • Description element (line 5) (optional): additional information about the package. May contain publisher, vendor or developer information up to 1000 characters.
  • ReleaseDate element (line 6) (required): Must contain a well-formed date. ISO date format (e.g. '2014-04-16' or '2014-04-16 12:30:00') is recommended.
  • VersionControl element (line 7) (required, if the level is not Tool): the attributes of this element contain Windows-style version information in the following format: major.minor.build.revision (for example 2.1.3.4567): four integers joined with dots without whitespaces.
    • target attribute (line 8) (required, if the level is not Tool): In case of Tool level this attribute is prohibited. Determines the version of the Sense/Net product or the application after the package is installed. The target version must be greater than the last installed package if the level is Patch, ServicePack or Upgrade.
    • expected attribute (line 9): This is the most common prerequisit. Determines the exact required version of the Sense/Net product or the application (depending on the type of the package). If the current official version does not match this expectation, the package will not be executed.
    • expectedMin attribute (line 10): Determines the expected minimum version of the related component. Must not be present if the 'expected' attribute is provided.
    • expectedMax attribute (line 11): Determines the allowed maximum version of the related component. Must not be present if the 'expected' attribute is provided.

Please note that in the current version of the packaging framework there is no built-in prerequisite check for the core product in case of application packages. Developers may check the current product version in a custom install step using the packaging API.

In some cases it may be necessary to inform the operator after the package execution about the result. There are two optional elements for this purpose in the head of the manifest:

  • SuccessMessage element (optional): Displays the element's inner text when the package execution was successfull.
  • WarningMessage element (optional): Displays the element's inner text when the package execution is terminated by a Terminate step and its Reason property is Warning.
  • ErrorMessage element (optional): Displays the element's inner text when the package execution completed with an error.
<Package ...
  ...
  <SuccessMessage>The tool has been successfully executed.</SuccessMessage>
  <WarningMessage>The tool has been terminated by a Terminate step. See the warning message above.</WarningMessage>
  <ErrorMessage>Execution finished with a serious error. Please restore the database and the web folder.</ErrorMessage>
  <Steps>
  ...
Error message
Warning message
Success message

If the package execution is not repeatable (e.g. because it contains complicated steps that must not be executed more than once) it is strongly recommended to inform the operator in an error message that he needs to restore the database and the web folder before executing the package again. It is advisable however that you design your package in a way that it can be executed more than once. E.g. use existence checks in SQL scripts and config file modifications.

Example

The following sample manifest contains a couple of common steps:

  • deploys a new version of some libraries
  • starts the repository
  • imports new content types
  • imports new content items
<Package type='Application' level='Patch'>
  <Name>Sense/Net ECM</Name>
  <Edition>Enterprise</Edition>
  <VersionControl target='1.1.0' expected='1.0.0' />
  <ReleaseDate>2014-09-19</ReleaseDate>
  <Steps>    
      <!--==================================== Web binaries ====================================-->
 
      <Copy targetDirectory='bin' source='bin\MyCustomLibrary.dll' />
      <Copy targetDirectory='bin' source='bin\PluginLibrary.dll' />
 
      <!--==================================== Content Repository changes ====================================-->
 
      <StartRepository />
 
      <!--=========================== Content type modifications ===========================-->
 
      <ImportSchema source='schema' />
 
      <!--============================== Content modifications =============================-->      
 
      <Import source='import' target='/Root' />
  </Steps>
</Package>

Steps

The list of steps in the manifest describes what a package will actually do. You can see a list of the things a step can do above. After the package manager extracted the zip into the file system and checked prerequisites, the steps are executed one after another.

A step xml element in the manifest file appoints the code that will be executed and also defines the properties of a step codebehind class using xml attributes.

Step name

The name of a step element in the XML is the step class name. Developers may override the default name in source code. SnAdmin allows you to use the fully qualified name of the underlying step class. In case of name duplication, you can use the fully qualified name instead of the short name of the step. For example the following two steps are equivalent:

<Delete>App_Data\readme.txt</Delete>
<SenseNet.Packaging.Steps.Delete>App_Data\readme.txt</SenseNet.Packaging.Steps.Delete>

The short and full names of the built-in steps can be found in the Built-in steps section below.

Step properties

The step XML element may have some properties. Readability depends on the number of the properties and their length and complexity. Because there is no single perfect solution for this, to increase readability of the manifest XML the properties can appear either as XML attributes or sub-elements of the step element. And if the developer defines a 'default property', then the value can appear as the inner text of the step element also. Attribute or element names and the mapped property names are equal. So there are three ways to define a step property. In the following example we define a custom step that's name is Compare and has two properties: SourceFile (default property) and TargetFile:

The attribute model:

<Compare sourceFile="files\readme.txt" targetFile="bin\readme.txt" />

The default-property model (default property is explicitly defined by the developer):

<Compare targetFile="bin\readme.txt">files\readme.txt</Compare>

The element model:

<Compare>
    <SourceFile>files\readme.txt</SourceFile>
    <TargetFile>bin\readme.txt</TargetFile>
</Compare>

The step definitions above are equivalent. There are two prohibited mixed models:

Attribute and element name collision in the mixed model CAUSES AN EXCEPTION:

<Compare sourceFile="files\readme.txt">
    <SourceFile>files\readme.txt</SourceFile>
    <TargetFile>bin\readme.txt</TargetFile>
</Compare>

Using sub-elements and default property in one model CAUSES AN EXCEPTION:

<Compare>
    files\readme.txt
    <TargetFile>bin\readme.txt</TargetFile>
</Compare>

The attributes or sub-elements will be mapped to the strongly typed properties automatically. The type of a property must be IConvertible. The XML values will be converted through this interface from string to the target type. If the property is not convertible, an InvalidPackageException will be thrown.

File paths in steps

Steps often reference files or folders that can be sources or targets. They are usually file system paths, but in a few cases they can be Content Repository paths, depending on the capabilities of the step (e.g. Delete). Our recommendation is that source files always mean files in the current package and target files mean files in the current web directory. If this can be kept the paths can be relative:

  • source paths are relative to the current package root
  • target paths are relative to the current web directory.

Please note that a package is not portable if just one path is absolute. All built-in steps use relative paths. It is strongly recommended to use this approach in all custom steps too.

Conditional steps

From version 6.3.1 patch 2 it is possible to execute steps based on a condition. This means a step (or a list of steps) is executed only if a given condition is fulfilled. For example a config file is modified only if the file actually exists. Or you can check if a certain content exists in the Content Repository.

<IfFileExists Path="custom.config">
   <Then>
      <Step1 />
   </Then>
   <Else>
      <Step2 />
      <Step3 />
   </Else>
</IfFileExists>

There is no generic IF step, because different conditions may have many different properties. Please look for the built-in conditional steps, or create your own custom conditional step by inheriting from the following base class:

  • SenseNet.Packaging.Steps.ConditionalStep

Built-in steps

There are many built-in steps in the product that you can use to build your own packages. Please check the following article for the complete list:

Custom Steps

It is possible to create custom install steps for the packaging framework. This is the way to customize the install process for custom applications built on Sense/Net, executing ad-hoc tools and hotfixes. Please visit the following article for details:

Phases

It is possible to define multiple lists of steps inside a package (in the manifest). These lists are called Phases and they serve only one purpose: you need to place steps which need a different dll set into separate phases. For example you need to perform a couple of tasks with the old dll set (e.g. export content using the old content handlers), then switch to the new dlls inside the package. In this case you put the first steps (including the copy step) into the first phase and put the rest to the next phase.

SnAdmin tool will restart itself between phases and will be executed with the new dll set. The execution will continue with the step where it left off.

Phase example

<Steps>
	<Phase>
		<Export />
		<Copy />
	</Phase>
	<Phase>
		<Delete />
		<Import />
	</Phase>
</Steps>

Each phase is independent during the SnAdmin execution. It means every phase is parsed and executed independently. This way it is possible to install or upgrade a class library with new step types and use these in a following phase in the same package. This execution model has only one disadvantage: if the manifest xml contains invalid parts in a later phase, an exception will be thrown only in the incorrect phase after the successful execution of the previous phases. In this case the package may leave unwanted elements in the database or the file system. To minimize the chance of these cases you always need to test the package on a test server before executing it on a production server.

Directory structure in the package

The package zip file should contain only one XML file in the root (the manifest), all additional content should be in subfolders. There is no naming convention for the subfolders - except the one for developers.

You can name your folders as you wish, but it is recommended to follow these rules:

  • provide content files to import in a separate folder (e.g. called Root or ContentFiles)
  • provide libraries in a separate folder (e.g. Executables or Libraries)

You will have to reference these folders in your manifest file at the appropriate step.

Executing a package

In this section you will learn how to use the SnAdmin tool to execute a package, what is happening in the background and how to monitor and troubleshoot the process.

SnAdmin directory structure

In this section we describe the recommended directory structure of the SnAdmin tool in the file system. For details about the full structure of the web folder, please visit the following article:

From version 6.3.1 Patch 2

From this version the default behaviour is that the SnAdmin feature resides inside the web application in a subfolder called Admin.

We created the default Web folder structure to make automatic updates easier. It is advisable to keep the default structure intact to avoid manual updates later.

<Drive>:\
    ....
    <WebSite>
        bin
        App_Data
        ....
        Web.config
        Admin
            bin
                SnAdmin.exe
                ....
            run
                ....
            log
                Package1_20140429-034910.log
                ....
            Package1
                ....
                Manifest.xml
            Package1.zip

Before version 6.3.1 Patch 2

Our suggestion is that you keep the web and the admin folders separate as siblings, and the admin folder's name should be WebSite + _admin.

<Drive>:\
    ....
    <WebSite>
        bin
        App_Data
        ....
        Web.config
    <WebSite>_admin
        bin
            SnAdmin.exe
            ....
        run
            ....
        log
            Package1_20140429-034910.log
            ....
        Package1
            ....
            Manifest.xml
        Package1.zip

For example a good combination is: C:\Webs\MyWeb for the web, C:\Webs\MyWeb_admin for packaging, and the running SnAdmin is: C:\Webs\MyWeb_admin\bin\SnAdmin.exe.

SnAdmin subfolders

The subfolders below are the same both before and after the version 6.3.1 Patch 2.

  • bin: Place of the SnAdmin.exe, it's configuration file and referenced assemblies. SnAdmin must be launched from here. If you do not have this folder yet, you can just create the folders as shown above and copy the libraries from the <WebSite>\bin folder (only before version 6.3.1 Patch 2). If you do not have the SnAdmin tool itself, you can get it by compiling the source package of SenseNet ECMS.
  • run: Automatically created directory for sandboxing the phases. Every phase starts with cleaning up this folder, copying the files from the admin\bin folder (see the previous entry) and the <WebSite>\bin folder, then executes the SnAdmin tool from here. This concept supports <WebSite>\bin manipulations without locking files.
  • log: Automatically created directory for storing log files. Every SnAdmin execution creates a log file. The name is the package name suffixed with date and time (e.g. Package1.zip_20140429-034910.log).

From version 6.3.1. Patch 2 the SnAdmin tool is really standalone and does not have any references to the core product dlls. This means the admin\bin folder may contain only the SnAdmin tool and the Ionic.Zip library, and you do not have to copy all the dlls from the web\bin folder.

Configuration

The SnAdmin tool has its own config file that contains the following values related to package execution.

Before version 6.3.1 Patch 3: the following configuration items can be found in the admin\bin\SnAdmin.exe.config file.

From version 6.3.1 Patch 3: the following configuration items can be found in the web\Tools\SnAdminRuntime.exe.config file.

It is recommended to omit the optional values and let the tool fallback to the default values when it is possible.

  • TargetDirectory (optional, use it only before Patch 3): absolute path of the web directory (parent of web.config). Default: sibling directory of the current package directory if the directory names correspond to the following convention:
    • Web and package directories are siblings.
    • Package directory name is Web directory name + _admin.
    • SnAdmin is running under the Package directory.
  • PackageDirectory (optional): absolute or relative path of the package directory. Default: '..\..\' because the running exe is in the package_dierctory\bin by default.
  • NetworkTargets (optional): web directory paths on remote web servers in case of NLBS environment. Comma or semicolon separated list of UNC paths. For example: \\Server1\SensenetWeb;\\Server2\SensenetWeb.
  • ClusterChannelProvider: see MSMQ article. This is mandatory in an NLBS environment.
  • MsmqChannelQueueName: see MSMQ article. This is mandatory in an NLBS environment.
  • IndexDirectoryPath (optional): Container directory of the the Lucene indices. Can be absolute or relative to the TargetDirectory. Default: 'LuceneIndex' directory in the target directory's App_Data.
  • EnableOuterSearchEngine: switches on or off the instant indexing. Our recommendation: always "true" (switched on).

Config examples

Default structure and single server

<!--<add key="TargetDirectory" value="" />-->
<!--<add key="PackageDirectory" value="..\..\" />-->
<!--<add key="NetworkTargets" value="\\Server1\SensenetWeb;\\Server2\SensenetWeb" />-->
 
<!--<add key="ClusterChannelProvider" value="SenseNet.Communication.Messaging.MsmqChannelProvider, SenseNet.Storage" />-->
<!--<add key="MsmqChannelQueueName" value=".\private$\server1;.\private$\server2" />-->
<!--<add key="IndexDirectoryPath" value="" />-->
<add key="EnableOuterSearchEngine" value="true" />

Default structure and NLBS

<!--<add key="TargetDirectory" value="" />-->
<!--<add key="PackageDirectory" value="..\..\" />-->
<add key="NetworkTargets" value="\\Server1\SensenetWeb;\\Server2\SensenetWeb" />
 
<add key="ClusterChannelProvider" value="SenseNet.Communication.Messaging.MsmqChannelProvider, SenseNet.Storage" />
<add key="MsmqChannelQueueName" value=".\private$\server1;.\private$\server2" />
<!--<add key="IndexDirectoryPath" value="" />-->
<add key="EnableOuterSearchEngine" value="true" />

Custom structure

<add key="TargetDirectory" value="C:\..." />
<add key="PackageDirectory" value="..\..\" />
 
<add key="IndexDirectoryPath" value="C:\....\LuceneIndex" />

Arguments

When you start the SnAdmin tool, there are a couple of arguments you can use to customize its behavior.

SnAdmin[.exe] <package> [<target>] [LOGLEVEL:<loglevel>] [-HELP|-?]
  • <package>: Zip package file or directory. Can be a name, relative or absolute path of the package to execute.
  • <target>: Web directory of a stopped SenseNet instance. This argument overrides the configured or default value.
  • <loglevel>: use this to customize the logging level of the package execution. Available values:
    • Default: Package information will be written to the database, execution process will be written to a log file and to the console.
    • File: Package information will not be written to the database. The execution process will be written to a log file and to the console.
    • Console: Information will be written to the console only.
    • Silent: No feedback at all.
  • -HELP or -?: Prints out all loaded assemblies and available step types and their parameters.

Execution examples

Default structure and single server 1

C:\MyWeb_admin\bin\SnAdmin package1
  • If 'package1' directory exists, the extraction is skipped.
  • If 'package1' directory does not exist, the zip file with the same name will be extracted under the newly created 'package1' directory.
  • If 'package1.zip' does not exist, the tool will be terminated with a 'Given package file does not exist' error message.

Default structure and single server 2

C:\MyWeb_admin\bin\SnAdmin package1.zip
  • If 'package1.zip' file does not exist, the tool will be terminated with a 'Given package file does not exist' message.
  • If 'package1' exists, it will be deleted and re-created (this is a different behavior than in the previous example!).
  • The package will be extracted under the 'package1' directory.

Information about loaded assemblies and available steps

C:\MyWeb_admin\bin\SnAdmin package1.zip -HELP

The loaded assemblies and step / parameter list appear on the console. The lists contain the steps from extension dlls that are in the PackageCustomization directory under the current package:

===============================================================================
                              Sense/Net Admin v1.0
===============================================================================
Start at 2014-05-05 10:43:09
Target:  C:\........\Source\SenseNet\WebSite
Package: C:\........\Source\SenseNet\WebSite_admin\TestPackage1
Loading package customizations:
  DemoInstallSteps.dll
Assemblies:
  AjaxMin, Version=4.51.4507.18296, Culture=neutral, PublicKeyToken=21ef50ce11b5d80f 4.51.4507.18296 Release
  ....
  SenseNet.ContentRepository, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null 1.0.0.0 Debug
  ....
  SnAdmin, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null 1.0.0.0 Debug
  ....
  System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 4.0.0.0 Release
  mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 4.0.0.0 Release
 
Available step types and parameters
-----------------------------------
Trace (SenseNet.Packaging.Steps.Trace)
  Text : String (Default)
Delete (SenseNet.Packaging.Steps.Delete)
  Path : String (Default)
ImportSchema (SenseNet.Packaging.Steps.ImportSchema)
  Source : String (Default)
Import (SenseNet.Packaging.Steps.Import)
  Target : String
  Source : String (Default)
Copy (SenseNet.Packaging.Steps.Copy)
  Source : String (Default)
  TargetDirectory : String
  NewName : String
StartRepository (SenseNet.Packaging.Steps.StartRepository)
ExecuteDatabaseScript (SenseNet.Packaging.Steps.ExecuteDatabaseScript)
  Query : String (Default)
ContentCountCondition (DemoInstallSteps.ContentQueryPrerequisit)
  Query : String (Default)
  CountMin : Int32
  CountMax : Int32
  Terminate : Boolean
 
===============================================================================
SnAdmin has been successfully finished.
Ok
See log file: C:\........\Source\SenseNet\WebSite_admin\log\TestPackage1_20140505-104309.log

Logging

Log files are placed into the log folder of the package directory, into a separate folder for every package and date. A log file head contains the following data:

  • SnAdmin version number
  • Package execution date-time
  • Package name
  • Information about extracting the package (if it is a zip file)
  • Manifest head information: Package name, type, level, edition, AppId, current version

During execution, the log file will contain:

  • a title for each phase and steps
  • duration of every step execution
  • duration of the tool running
  • error count

Log file example

03:59:10.0078    ===============================================================================
03:59:10.0088                                  Sense/Net Admin v1.0
03:59:10.0098    ===============================================================================
03:59:10.0148    Start at 2014-04-29 03:59:10
03:59:10.0178    Target:  C:\Dev10\SenseNet\Development\Budapest\Source\SenseNet\WebSite
03:59:10.0208    Package: C:\Dev10\SenseNet\Development\Budapest\Source\SenseNet\WebSite_admin\TestPackage2.zip
03:59:10.0268    Package directory: C:\Dev10\SenseNet\Development\Budapest\Source\SenseNet\WebSite_admin\TestPackage2
03:59:10.0308    Old files and directories are deleted.
03:59:10.0328    Extracting ...
03:59:10.0948    Ok.
03:59:10.7779    Name:    TestTool
03:59:10.7789    Edition: 
03:59:10.7799    Type:    Product
03:59:10.7859    Level:   Tool
03:59:12.0460    Current version: 6.3.1
03:59:12.7081    ===============================================================================
03:59:12.7101                                  Executing phase 1/1
03:59:12.7111    ===============================================================================
03:59:12.7151    Executing steps
03:59:12.7171    ================================================== #1/3 TestStep
                TestStep's place...
03:59:12.7631    -------------------------------------------------------------
03:59:12.7691    Time: 00:00:00.0459051
03:59:12.7711    ================================================== #2/3 LogTester
                LogTester step's place...
03:59:12.7821    -------------------------------------------------------------
03:59:12.7871    Time: 00:00:00.0113655
03:59:12.7891    ================================================== #3/3 LogTester
                LogTester step's place...
03:59:12.8001    -------------------------------------------------------------
03:59:12.8041    Time: 00:00:00.0109782
03:59:12.8071    =============================================================
03:59:12.8101    All steps are executed.
03:59:12.8151    Aggregated time: 00:00:00.0916766
03:59:12.8191    Errors: 0
03:59:12.9611    ===============================================================================
03:59:12.9621    SnAdmin has been successfully finished.
03:59:12.9631    Ok

Getting package information

After executing a package you can check the packages with a specific OData function:

http://example.com/OData.svc('root')/GetVersionInfo

This function returns a complex object that contains all packaging information: installed Sense/Net version, installed applications with their valid version, loaded assemblies, and all executed packages.

Package execution result

In most cases packages are executed successfully, but sometimes the execution fails - maybe because there was a conflict in the Content Repository or an unexpected exception occured during execution. We register the result of every package execution to let administrators keep track of what happened. The possible outcomes are the following:

  • Successful: the package executed correctly
  • Faulty: there was an error during execution (see the ExecutionError property below for details)
  • Unfinished: the package stopped and must be re-executed (e.g. because of a power outage)

If the execution was not successful, you must correct the possible errors and execute the package again, because the database may be in an unknown state. In case of complex packages the best solution is to restore the database and execute the corrected package on it.

In the example below you can see the list of all the successful and unsuccessful packages - the package history.

Example

The following example demonstrates how package information looks like in a real life scenario. After an application installation there was an unsuccessful patch that was repaired and executed again. After that the packaging information looks like as follows (edited for clarity):

{
  "OfficialSenseNetVersion": {
    "Name": "Sense/Net ECM",
    "Edition": "Unofficial",
    "AppId": null,
    "Version": "6.3.1",
    "AcceptableVersion": "6.3.1",
    "Description": "This edition can only be used for development and testing purposes."
  },
  "Applications": [
    {
      "Name": "MyApplication",
      "Edition": null,
      "AppId": "0BF502A1-0019-469F-8D13-45807B2E9667",
      "Version": "1.0.1",
      "AcceptableVersion": "1.0.1",
      "Description": "MyApplication install package"
    }
  ],
  "Assemblies": {
    "SenseNet": [
      {
        "Name": "SenseNet.BackgroundOperations, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null",
        "IsDynamic": false,
        "CodeBase": "C:\\Dev10\\SenseNet\\Development\\Budapest\\Source\\SenseNet\\WebSite\\bin\\SenseNet.BackgroundOperations.DLL",
        "Version": "1.0.0.0 Debug"
      },
      ...
 
    "Plugins": [
      {
        "Name": "AjaxMin, Version=4.51.4507.18296, Culture=neutral, PublicKeyToken=21ef50ce11b5d80f",
        "IsDynamic": false,
        "CodeBase": "C:\\Dev10\\SenseNet\\Development\\Budapest\\Source\\SenseNet\\WebSite\\bin\\AjaxMin.DLL",
        "Version": "4.51.4507.18296 Release"
      },
	  ...
 
    "GAC": [
      {
        "Name": "Microsoft.VisualBasic.Activities.Compiler, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a",
        "IsDynamic": false,
        "CodeBase": "C:\\Windows\\Microsoft.Net\\assembly\\GAC_64\\Microsoft.VisualBasic.Activities.Compiler\\v4.0_10.0.0.0__b03f5f7f11d50a3a\\Microsoft.VisualBasic.Activities.Compiler.dll",
        "Version": "10.0.0.0 Release"
      },
	  ...
 
    "Other": [
      {
        "Name": "mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
        "IsDynamic": false,
        "CodeBase": "C:\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319\\mscorlib.dll",
        "Version": "4.0.0.0 Release"
      },
	  ...
 
    "Dynamic": [
      {
        "Name": "Anonymously Hosted DynamicMethods Assembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null",
        "IsDynamic": true,
        "CodeBase": "",
        "Version": ""
      },
      ...
    ]
  },
  "InstalledPackages": [
    {
      "Id": 1,
      "Name": "Sense/Net ECM",
      "Edition": "Unofficial",
      "Description": "This edition can only be used for development and testing purposes.",
      "AppId": null,
      "PackageLevel": 4,
      "PackageType": 0,
      "ReleaseDate": "2014-07-24T01:47:56.457Z",
      "ExecutionDate": "2014-07-24T01:47:56.457Z",
      "ExecutionResult": 0,
      "ApplicationVersion": null,
      "SenseNetVersion": "6.3.1",
      "ExecutionError": null
    },
    {
      "Id": 13,
      "Name": "MyApplication",
      "Edition": null,
      "Description": "MyApplication install package",
      "AppId": "0BF502A1-0019-469F-8D13-45807B2E9667",
      "PackageLevel": 4,
      "PackageType": 1,
      "ReleaseDate": "2014-07-20T00:00:00Z",
      "ExecutionDate": "2014-07-28T02:53:49.283Z",
      "ExecutionResult": 0,
      "ApplicationVersion": "1.0",
      "SenseNetVersion": "6.3.1",
      "ExecutionError": null
    },
    {
      "Id": 14,
      "Name": "MyApplication",
      "Edition": null,
      "Description": "Small technical update for install package",
      "AppId": "0BF502A1-0019-469F-8D13-45807B2E9667",
      "PackageLevel": 1,
      "PackageType": 1,
      "ReleaseDate": "2014-07-22T00:00:00Z",
      "ExecutionDate": "2014-07-28T02:53:56.38Z",
      "ExecutionResult": 1,
      "ApplicationVersion": "1.0.1",
      "SenseNetVersion": "6.3.1",
      "ExecutionError": {
        "ClassName": "System.Data.SqlClient.SqlException",
        "Message": "Invalid object name 'tblPackages'.",
        "Data": {
          "HelpLink.ProdName": "Microsoft SQL Server",
          "HelpLink.ProdVer": "10.00.5512",
          "HelpLink.EvtSrc": "MSSQLServer",
          "HelpLink.EvtID": "208",
          "HelpLink.BaseHelpUrl": "http://go.microsoft.com/fwlink",
          "HelpLink.LinkId": "20476"
        },
        "InnerException": null,
        "HelpURL": null,
        "StackTraceString": "   at System.Data.SqlClient.SqlConnection.OnError(SqlException exception, Boolean breakConnection, Action`1 wrapCloseInAction)\r\n...",
        "RemoteStackTraceString": null,
        "RemoteStackIndex": 0,
        "ExceptionMethod": null,
        "HResult": -2146232060,
        "Source": ".Net SqlClient Data Provider",
        "WatsonBuckets": null
      }
    },
    {
      "Id": 15,
      "Name": "MyApplication",
      "Edition": null,
      "Description": "Small technical update for install package",
      "AppId": "0BF502A1-0019-469F-8D13-45807B2E9667",
      "PackageLevel": 1,
      "PackageType": 1,
      "ReleaseDate": "2014-07-21T00:00:00Z",
      "ExecutionDate": "2014-07-28T02:54:05.54Z",
      "ExecutionResult": 0,
      "ApplicationVersion": "1.0.1",
      "SenseNetVersion": "6.3.1",
      "ExecutionError": null
    }
  ]
}

The version info contains the following object types and their enumerations in the appropriate properties:

  • ApplicationInfo: The OfficialSenseNetVersion and the Applications enumeration contain these objects. The properties:
    • Name: Name of the package.
    • Description: Description of the package. It is strongly recommended that the package name and description contain real name and aim of the package.
    • Edition: Edition of the application or null.
    • AppId: Application's unique identifier,
    • Version: Version number (as a string e.g. "1.0.1") that was defined in the package,
    • AcceptableVersion: The real version number of the application, that means "the last good".
  • AssemblyDetails: This objects appear in the categorized assembly list under the Assemblies property.
    • Name: assembly's full name (e.g. "SenseNet.BackgroundOperations, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"),
    • IsDynamic: The value is "true" if the assembly exists only in the memory. In this case the CodeBase and the Version properties contain empty string.
    • CodeBase: place of the assembly e.g. "C:\\...\\WebSite\\bin\\SenseNet.BackgroundOperations.DLL",
    • Version: e.g. "1.0.0.0 Debug"
  • Package: Objects under the InstalledPackages property
    • Id: Identifier of the package execution.
    • Name: Package name.
    • Edition: Edition of the application or null.
    • Description: Package description,
    • AppId: Application's unique identifier,
    • PackageLevel: 4,
    • PackageType: 1,
    • ReleaseDate: "2014-07-20T00:00:00Z",
    • ExecutionDate: "2014-07-28T02:53:49.283Z",
    • ExecutionResult: 0 - Successful, 1 - Faulty, 2 - Unfinished
    • ApplicationVersion: Version of the package. The copy of the "VersionControl" element's "target" attribute in the package (e.g. "1.0"),
    • SenseNetVersion: Version of the Sense/Net when the package was executes (e.g. "6.3.1"),
    • ExecutionError: The value is null if the execution was successful otherwise the execution exception is serialized here.

Overriding package properties

It is possible to override any property of any step in a package using command line arguments of the SnAdmin tool. This lets you customize a package without having to modify it manually. This can be done by providing the step, the property and its new value as command line arguments. The format is the following:

SnAdmin PackageName [PhaseX.]StepY[.PropertyName]:PropertyValue
  • The Phase keyword (case insensitive) and the 1-based index of the phase in the package. Optional, default is 1.
  • The Step keyword (case insensitive) and the 1-based index of the step in the package. Required.
  • Property name (case insensitive). Optional, the default is the default property.
  • Property value (can be empty) (the value will be converted using the IConvertible interface).

Overriding examples

SnAdmin Package1 PHASE2.STEP3.Text:"Hello world": Overrides the "Text" property of step 3 in phase 2 with the value "Hello world".
SnAdmin Package1 STEP3.Text:"Hello world": Overrides the "Text" property of step 3 in phase 1 with the value "Hello world".
SnAdmin Package1 STEP3:"Hello world": Overrides the default property of step 3 in phase 1 with the value "Hello world".


Updating Task executors

If you are using the Task Management component, you will have to update the task executors related to Sense/Net ECM (e.g. the preview generator or the AD synchron tools) manually. The reason behind this is that the Task Management component itself is a standalone application that is independent from Sense/Net ECM and the executors are deployed in the different place than the main Sense/Net ECM web application.

As the latest executor tools are deployed in the web\TaskManagement folder of Sense/Net ECM in the same structure as task management expects it, you only have to copy the latest files to your task management environment (agent machines). The only thing you have to take care of is merging configuration files manually. For details see the following article:

Related links

References

Names of Namespaces