Export (0) Print
Expand All

CSPack Command-Line Tool

Updated: October 24, 2014

The CSPack Command-Line Tool (CSPack.exe) prepares an application for deployment. How you use CSPack depends on where you intend to deploy the application.

  • To prepare the application for deployment to the Microsoft Azure compute emulator, use CSPack to copy the binary files to a directory layout.

  • To prepare the application for deployment to Windows Azure, use CSPack to generate a package file that is uploaded to Windows Azure.

  • To convert an existing package to the new package format, for more information, see Windows Azure Package Format

If you installed the SDK to the default location, for Windows Azure SDK versions 1.7 and greater, CSPack can be found in the C:\Program Files\Microsoft SDKs\Windows Azure\.NET SDK\<sdk-version>\bin directory. In Windows Azure SDK versions 1.6 and earlier, CSPack is installed to the C:\Program Files\Windows Azure SDK\<SDK version>\bin\ directory.

CSPack <DefinitionFile> [options]

The following table lists the options for CSPack. To view the most current option list, type CSPack /? at a command prompt from the installed location.

 

Option Description

/out:<file> | directory>

This option indicates the output format and location for the role binaries.

When the /copyOnly option is specified together with this option, CSPack creates the named output directory and copies the role binaries to that directory.

If /copyOnly is not specified, this option specifies the file name for the application package. If no file name is specified, the application package is created as <service-definition-file-name>.cspkg.

/copyOnly

When this option is specified, CSPack creates a directory layout for the role binaries, which the compute emulator uses to run the application locally.

If no output location is specified with the /out option, CSPack creates a directory named <service-definition-file-name>.csx.

/role:<RoleName>;[<RoleBinariesDirectory>];[<RoleEntryPointDLL>]

When this option is specified, CSPack creates a directory layout for the role binaries, which the compute emulator uses to run the application locally.

If no output location is specified with the /out option, CSPack creates a directory named <service-definition-file-name>.csx.

/roleFiles:<RoleName>;<RoleFileList>

This option specifies a file that includes a set of paths to the files that comprise the role. The command line may include one /roleFiles option for each role denoted in the definition file.

To specify the DLL that defines the entry point of the role, use the /rolePropertiesFile option together with the /roleFiles option.

The <RoleFileList> parameter specifies a simple local text file where each line is of the following form:

<InputPath>;<TargetPath>

The <InputPath> may be either an absolute path or a relative path to a file that comprises the role. If the <InputPath> is relative, it is relative to the location of the file specified by <RoleFileList>.

The <TargetPath> is a relative path that specifies where the file referred to by <InputPath> is to be placed in the service package.

If you specify the /roleFiles option, you should not also specify the /role option.

/rolePropertiesFile:<RoleName>;<RolePropertyFile>

This option specifies a file that contains a list of properties for a role. The /rolePropertiesFile option should be specified together with the /roleFiles option. Within the role property file, you can specify the DLL that contains the entry point to the role and the target .NET framework version against which this role should run.

The <RolePropertyFile> parameter specifies a simple local text file where each line is of the following form:

<PropertyName>=<PropertyValue>

For details on valid property names and values, see the Remarks section.

/sitePhysicalDirectories:<RoleName>;<VirtualPath1>;
<PhysicalPath1>;<VirtualPath2>;<PhysicalPath2>;…

This option enables the definition of physical directories for each virtual path defined in the Sites section. Each Site, Virtual Directory, and Virtual Application element creates a virtual path (also called a location path in the web.config location element).

For more information about using the Site element, see Configure the Site Entry in the Service Definition File.

/sites:<RoleName>;<SiteName>;<VirtualPath1>;
<PhysicalPath1>;…

This option enables the mapping of the content located in physical directories to the virtual directories of the web site. Each Site, Virtual Directory, and Virtual Application element is appended in order they are defined to create the virtual paths (also called a location path in the web.config location element).

VirtualPath1 maps to the site name of as defined by the name attribute of the <Site> element in the service definition file.

PhysicalPath1 is the location of the Site contents.

/generateConfigurationFile:<ConfigurationFile>

This option is used to generate a skeleton configuration file for an application. Edit the generated file to specify the values of the settings and number of role instances in the application before you deploy it.

/allowLegacyWebRoles

This flag suppresses warnings that occur for a package that contains legacy web roles that run in Hosted Web Core. You can run the role instances in a Hosted Web Core by using this option or you can add the Sites element to your service definition.

/useCtpPackageFormat

This option specifies that the package is formatted in the new package format. See Use CSPack to create a package in the new format for information about using the new format.

/convertToCTPPackage

This option specifies that an existing package is to be converted to the new package format. For more information, see Convert an existing package to the new format.

You can specify the following properties in the role property file:

noteNote
Having trouble viewing this topic in the Windows Azure library? Try viewing it in the MSDN library.

 

Property Name Property Value Examples

TargetFrameWorkVersion

A number indicating the version of the .NET Framework against which this role is to be run. The format for this property setting is TargetFrameWorkVersion=vMajor.Minor, where Major refers to the major release number, and Minor refers to the minor release number.

TargetFrameWorkVersion=v4.0

TargetFrameWorkVersion=v3.5

EntryPoint

The name of the DLL that serves as the entry point into the role. The format for this property setting is EntryPoint=DLLFileName, where DLLFileName is a string that specifies the file name of the DLL.

EntryPoint=myroleentrypoint.dll

ImportantImportant
If a call to CSPack that worked against the Windows Azure SDK 1.1 fails after upgrading to the Windows Azure SDK 1.2 or later, the problem may be that you have not correctly specified the .NET target framework version for CSPack. CSPack assumes that your service code has been compiled under .NET 3.5 by default. If your code has been compiled under .NET 4, you must specify that by creating a role properties file and including the /rolePropertiesFile option on the command line.

WarningWarning
In Windows SDK version 1.5 and later, packages created by CSPack are no longer encrypted. It is recommended that you do not store sensitive data in the package contents.

The following examples show how to manually package several of the Windows Azure SDK samples from the command line using CSPack.

The following example shows how to package the HelloWorld sample for deployment in the development environment:


c:\samples\HelloWorld>cspack HelloWorld\ServiceDefinition.csdef /out:HelloWorld.csx /role:HelloWorld_WebRole;HelloWorld_WebRole /sites:HelloWorld_WebRole;Web;d:\HelloWorld_WebRole\HelloWorld_WebRole /copyOnly

The following example shows how to package the HelloWorld sample for deployment to Windows Azure:


c:\samples\HelloWorld>cspack HelloWorld\ServiceDefinition.csdef /out:HelloWorld.cspkg /role:HelloWorld_WebRole;HelloWorld_WebRole /sites:HelloWorld_WebRole;Web;d:\HelloWorld_WebRole\HelloWorld_WebRole

The following examples show how to package samples that include a worker role:


c:\samples\HelloFabric>cspack HelloFabric\ServiceDefinition.csdef 
   /role:HelloFabric_WorkerRole;HelloFabric_WorkerRole\bin\Debug;HelloFabric_WorkerRole.dll 
   /out:HelloFabric.cspkg

c:\samples\Thumbnails>cspack ThumbnailsWorkerOnly\ServiceDefinition.csdef 
/role:Thumbnails_WorkerRole;Thumbnails_WorkerRole\bin\Debug;Thumbnails_WorkerRole.dll 
/out:ThumbnailsWorkerOnly.cspkg

The following example shows how to package a sample that include both a worker role, OrderProcessingRole, and a web role, FrontendWebRole:


C:\samples\MultiTierApp>cspack MultiTierApp\ServiceDefinition.csdef /out:MultiTierApp.cspkg
/role:FrontendWebRole;FrontendWebRole /sites:FrontendWebRole;Web;c:\MyDirectory\MultiTierApp\FrontendWebRole 
/role:OrderProcessingRole;OrderProcessingRole\bin\Debug;OrderProcessingRole.dll

See Also

Show:
© 2014 Microsoft