Specification of a package

The .pkdesc file contains package metadata, and the definition of which files and folders to include in the package.

For command line parameters that you specify in the .pkdesc file, you do not need to specify the parameter on the command line. Any parameters specified in the .pkdesc file are appended to the command line arguments. If you specify a parameter in both the .pkdesc file and on the command line, then the command line specification takes precedence.

Package metadata

The package metadata is defined as attributes in the XML element <PackageDescription>. The attributes that can be set are listed in the table below.


XML attribute name	Optional or Required	Default value	Can be overridden on the command line	Comment
`SchemaVersion`	Required	N/A	No	Should always have the value "2.0".
`SeriesId`	Required	N/A	Yes "/id:"	This must be a GUID that uniquely identifies the package. Note: Make sure to generate a new ID if a .pkdesc file is copied.
`Name`	Required	N/A	Yes "/name:"
`Version`	Required	N/A	Yes "/packageversion:"	This is the version number for the package. It must contain 4 numbers separated by dots. For example, "1.2.3.4".
`IntendedClient`	Optional	"Forms"	Yes "/intendedclient:"	The possible values are: "Forms" or "Professional". The package is targeting the installed client only. "Web". The package is targeting the web client only. "Core" or "Any". The package is targeting both the installed client and the web client. "InformationServices". The package is targeting the Information Services service. Used for JDBC driver packages.
`IntendedPlatform`	Optional	"Windows"	Yes "/intendedplatform:"	One of the following: "Windows". The package is targeted for 64-bit Windows. "Linux". The package is targeted for 64-bit Linux. "Universal". The package is targeted for any platform.
`TargetFramework`	Optional	"Netframework"	Yes "/targetframework:"	One of the following: "Netframework". The package is targeted for .NET Framework. This also implies that `IntendedPlatform` is "Windows". "Netcore". The package is targeted for .NET Core (.NET 8 or higher). Currently, this implies that `IntendedPlatform` is Linux, but in some future also Windows could be supported. "Any". The package is targeted for any platform.
`WebPlayerContentFolder`	Optional	N/A	Yes "/wpcontentfolder:"	For Web packages only. The relative folder in the web client where the unpacked files are put. Do not use this unless necessary.
`Type`	Optional	N/A	No	For Information Services JDBC driver packages only. When creating such a package, set to: "JdbcDriver"
`Capability`	Optional	N/A	No	For Information Services JDBC driver packages only. When creating such a package, set to: "INFORMATION_SERVICES"
`LoadIsolated`	Optional	N/A	Yes "/loadIsolated" "/loadIsolatedKey:"	One of the following: "true" "false" Loads the assemblies in the package in an AssemblyLoadContext isolated from Spotfire. Equivalent to `/loadIsolatedKey:Spotfire.DefaultPluginLoadContext`. See also LoadIsolatedKey below.
`LoadIsolatedKey`	Optional	N/A	Yes "/loadIsolated" "/loadIsolatedKey:"	Possible value is a string. Loads the assemblies in the package in an AssemblyLoadContext identified by the provided key. Different packages can specify the same key to share a context across packages. Only applies to packages built for target framework `netcore`. See Loading multiple versions of as assembly for more information.

Note: There are some unsupported combinations of "IntendedPlatform" and "TargetFramework":

IntendedPlatform=Linux and TargetFramework=Netframework is not supported because Netframework is not available on Linux.
IntendedPlatform=Windows and TargetFramework=Netcore is currently not supported because the Windows clients are built using Netframework.

The table below shows the supported combinations of "IntendedClient", "IntendedPlatform" and "TargetFramework".

Note: The combination IntendedPlatform=Universal and TargetFramework=Any should only be used for packages that do not contain any .NET assemblies such as cobranding packages, resource files for localization, and so on.


IntendedClient	IntendedPlatform	TargetFramework
Core/Any	Universal	Any
Core/Any	Windows	Netframework
Core/Any	Linux	Netcore
Web	Universal	Any
Web	Windows	Netframework
Web	Linux	Netcore
Forms/Professional	Windows	Netframework

There is also a possibility to add metadata by specifying one or more child elements of the type <AlternativeId>. This can be used to have a single .pkdesc file that is used for building packages for both Windows and Linux, but also for different combinations of IntendedClient.

The attributes that can be set for <AlternativeId> are listed in the table below.


XML attribute name	Optional or Required	Default value	Comment
`IntendedClient`	Optional	"Forms"	The combination of this and the next two attributes must be a combination that is different from the attributes set for `<PackageDescription>` .
`IntendedPlatform`	Optional	"Windows"
`TargetFramework`	Optional	"Netframework"
`SeriesId`	Required	N/A	This must be a GUID that uniquely identifies the package with the combination of attributes above. It should be different from the specified `SeriesId` for the `<PackageDescription>`.
`Name`	Optional	The default name mentioned in `<PackageDescription>`	It is recommended to use a different name for a package than the default name, both to be able to identify the package on a deployment area of the Spotfire Server, but also when inspecting the modules on disk.

Note:

If no command line overrides for "IntendedClient", "IntendedPlatform" or "TargetFramework" are given on the command line, the default "SeriesId" and "Name" will be used for the package.
If an <AlternativeId> matches a command line override for "IntendedClient", "IntendedPlatform" or "TargetFramework" (missing overrides will be set to the default value), the following will happen:
- If either "/id:" or "/name" is given on the command line, the command line values take precedence over the attributes in the .pkdesc file.
- If one of "/id:" or "/name" is missing from the command line, the corresponding attribute from the matching <AlternativeId> will be used.

Package content

The package content is defined by the two child XML elements <File> and <Folder>.

These elements specify which files and folders to include in the package.

Note: To make it possible to use one .pkdesc file to specify packages that can be built for both Linux and Windows, it is possible to set attributes on these elements to indicate whether they should be included, depending on which command line options regarding "TargetFramework", "IntendedPlatform" and "IntendedClient" are used.

When using paths for the file or folder location, it is recommended to use forward slashes as a path separator.

File element

The attributes that can be set for <File> are listed in the table below.


XML attribute name	Optional or Required	Default value	Comment
`SourceFile`	Required	N/A	The path and the name of a file to include in the package. Note: The path to the file will be combined with the command line option "/basefolder:" which is provided from the command line.
`TargetFilename`	Optional	The path and the name of the source file.	If this is omitted, the path in the package will become the same as the specified path for the `SourceFile` attribute.
`Type`	Required	N/A	The supported file types are: "Assembly". This indicates that the file is a .NET assembly, either a Netframework or a Netcore assembly. The assembly references will be validated as part of the build step. "File". A file that is simply copied to the package. "ReferencedFile". A file that is referenced by one or more of the included assemblies but is expected to be pre-installed on the target machine. It could be in the GAC (for .NET Framework). This file is not copied to the package and the metadata for the package will contain information to the Spotfire Server that the file is not expected to be part of the content of the deployment area. "ReferencedFileInOtherPackage". An assembly that is expected to be included in some other package that will be part of the deployment. If any of the included assemblies in the package is referencing this file but it cannot be found on disk, it is regarded as OK. However, the validation of the deployment on the Spotfire Server will require that the file is included in some other package.
`IntendedClient`	Optional	N/A	The file will only be included if the `IntendedClient` for the package to create is matching. If missing, all clients match.
`IntendedPlatform`	Optional	N/A	The file will only be included if the `IntendedPlatform` for the package to create is matching. If missing, all platforms match.
`TargetFramework`	Optional	N/A	The file will only be included if the `TargetFramework` for the package to create is matching. If missing, all frameworks match.

It is possible to specify compatibility settings for assemblies by specifying the child element <Compatibility>. This element can have two optional attributes.


XML attribute name	Optional or Required	Default value	Comment
`Min-version`	Optional	The same version as the assembly itself.	'#' specifies that it is compatible with the corresponding digit in the version number. '*' means any number from 0 to 65535
`Max-version`	Optional	The same version as the assembly itself.	See above.

Because you cannot load two different versions of the same assembly, the code must be able to specify that a certain assembly can handle different version contracts.

For most assemblies, a higher version is compatible with a lower version. Use the <Compatibility> element to specify the required compatibility versions.

The contract for the min and max version for an assembly is:

“I am compatible with any version with the same strong assembly and with a version name between Min-version and Max-version that another assembly is referencing”.

For example, assume that assembly1.dll has been compiled against version "1.1.0.0" of assembly2.dll.

If the version of assembly2.dll is "1.2.0.0", when building a package including assembly1.dll and assembly2.dll, the compatibility setting for assembly2.dll must specify that Min-version is "1.1.0.0" or lower. Otherwise the validation will fail when creating the package.

Public resources is a way to specify that a file in a package can be found by calling the API method GetResourcePath(string resourceName) from the running instance of ModulesService.

The element is called <ResourceIdentifier> and can have two attributes.


XML attribute name	Optional or Required	Default value	Comment
`Name`	Required	N/A	This can be an arbitrary string but it must be unique except for different cultures, see below.
`Culture`	Optional	Invariant culture	If a culture attribute is set, the current UI culture for the running process is first tested to find a matching identifier. If no culture-specific culture is found, a search for an invariant culture that matches the name is performed.

Folder element

The attributes that can be set for <Folder> are listed in the table below.


XML attribute name	Optional or Required	Default value	Comment
`SourceFolder`	Required	N/A	The path to a folder to include in the package. Note: The path to the folder will be combined with the command line option "/basefolder:" which is provided from the command line.
`TargetFolder`	Optional	The path to the `SourceFolder`.	If this is omitted, the path in the package will become the same as the specified path for the `SourceFolder` attribute.
`IntendedClient`	Optional	N/A	The folder will only be included if the `IntendedClient` for the package to create is matching. If missing, all clients match.
`IntendedPlatform`	Optional	N/A	The folder will only be included if the `IntendedPlatform` for the package to create is matching. If missing, all platforms match.
`TargetFramework`	Optional	N/A	The folder will only be included if the `TargetFramework` for the package to create is matching. If missing, all frameworks match.

Public resources can be set by using the child-element <ResourceIdentifier> in the same way as for <File> elements, see File element above.

It is possible to set prefixes and suffixes for exclusions of files and sub-folders included in the SourceFolder element. This can be done by adding the element <ExcludePrefix> and/or the element <ExcludeSuffix>. The <ExcludeSuffix> was introduced in version 14.7.0 of Spotfire Developer. If used with older versions of Spotfire Developer, the element is ignored.

Note that there is no wild-card matching of support for regular expressions. All files and folders that begin with the <ExcludePrefix> will be excluded, as well as all files and folders that end with the <ExcludeSuffix>.

These elements can be repeated to create multiple filters for a given folder.

Module definition file

The module definition file, module.xml, that is included in the package, is always created based on the content of the .pkdesc file. In previous versions of Spotfire Developer, this file was partly manually updated, and partly updated by a tool which is no longer available. However, with the Package Builder console everything is handled automatically. It is possible to specify a <File> element in the .pkdesc file that automatically will save a copy of the module definition file when building a package, if desired.

In the example .pkdesc file included in the Templates folder of the SDK, there is an example on how to accomplish this if needed.