Rub a dub dub, a PUP in my tub Part I!

Article
01/02/2008

The Configuration of Commerce Server is stored in SQL Server database using Configuration APIs to manage it. To generate Commerce Server configuration you can use either the APIs or pre configured files. PUP which stands for Packaging and Unpackaging is used to create Commerce Server sites and resources. In this post I hope to shed some light on how Commerce Server PUP works.

What is PUP?

Site Packager application (Pup.exe) is a tool that packages or unpackages Commerce Server sites and resources into PUP files.

The Commerce Server documentation states that PUP is a deployment tool. I disagree, you should avoid deploying Commerce Server site from one environment to another. I use PUP is to manages the creation or extraction of Commerce Server sites or resources.

Is PUP the only way to create and extract Commerce Server Sites? No, you can use Commerce Server's Configuration APIs to do the same thing and I will show you how to do that. There has been some great post about PUP which you can find at the bottom for further reading.

PUP is responsible for the following operations:

Commerce Server Site
A Commerce Server Site includes a collection of site resources that define Commerce Systems such as Product Catalog, Inventory System, Orders System, Profiles System, Data Warehouse System and the Marketing System. These Systems can be accessed via APIs through ASP.NET, Console or WinForm Applications.
Site Resources
Site Resources are entities that provide configuration values to a Commerce Server Systems. Site Resources are local the to a Commerce Server Site and can not be shared. Sharing of site resources is only supported through import\export APIs or Global Resources.
Global Resources
Global Resources are an extension to Site Resources. A Site Resource can point to a global Resource which allows it to be shared among one or more Commerce Server sites.
Databases
Each Commerce Server System needs to store it's data some where, this storage is in SQL Server. The Site Resources have database connection strings to these databases.
OLAP database
Commerce Server uses OLAP to organize it's summarized data in the Data Warehouse so that report generation is completed faster.
Commerce Applications
A Commerce Site may have one ore more Commerce Application that maps to an IIS Site or Virtual Directory (VDir). These IIS Sites\VDir can be web site in a WebFarm or Web Services.
- IIS Applications
- IIS Metabase information

The Site Packager application can be used in two modes unattended\console and UI based. Using Site Packager application you can also add additional resources or Commerce Server Applications. PUP.exe will generate a log file under c:\pup.log and will append it's data for every execution of packages.

PUP stores and extracts it's data when unpackaging and packaging into MSCS_Admin database. For now we will concentrate on PUP and at later posts we dive deeper into MSCS_Admin database and Configuration API's.

UI PUP

When launching the PUP.exe you will navigate through the UI forms. Each form collects specific data then generates a Commerce Server Site or resource based on your responses and the data inside the PUP file.

Once the PUP.exe is launched you have two options Packaging an existing site or Unpackaging for a PUP file.

Unpackaging

If you select the Unpackage a PUP file you will navigate to next wizard form. On this form you need to enter the path of the PUP file and select either a Quick Unpack or Custom Unpack.

If you select a Quick Unpack the PUP.exe will select default values for you. If you have previously already selected a Quick Unpack then you run the danger of over writing your previous PUP settings. I always use the custom unpack as it allows me greater flexibility and control.
If you selected the Custom Unpack and selected Next. Then, on the next wizard form you select to:
- Create a new site
- Add resource in the package to an existing site
- Add an application in the package to an existing site
- Add a Web server to an existing application in an existing site
If you select a new site option then on the next form you will need to enter a unique site name.
On the next form you select the resources for your site.
Next you select the Global Resources for you site. Here you can either select a new global resource to be created for your site or use an existing one. If for whatever reason you selected a new global resource later on you can changed it by pointing the global pointer in the site resource.
Then you select the SQL server and databases. By default Commerce Server will create a database for each resource. For scalability reasons keep the Commerce Server Systems on separate databases.
On the next form you select which application to unpack.
Finally you can select which IIS site each application can be installed and name each application and IIS Virtual Directories. By selecting next the PUP will Unpack the site based on the answers you have provided so far.
During the Unpack you will be prompted for the profile xml files.
On the next wizard form you will need to select the SQL file for your profile structure.
Once the Unpackaging is complete on summary page you will be prompted to view any errors if occurred during the Unpackaging.

Unattended PUP

To launch the PUP.exe you must supply it two answer files. The answer files are ini files that holds responses to how the pup file should generate a Commerce Site.

Site Packager .ini File

The site packager .ini file control how a PuP file is deployed when you silently launch PUP. It is the answer file to all the Commerce Server System except Profiles System for that you will need BizData.ini.

BizData.ini File

The BizData.ini file is the answer file to Profiles System data related to a site. PUP.exe will look into the root folder (%COMMERCE_SERVER_ROOT%) of where Commerce Server is installed. So if you have customized the Profiles System then you need to put all the SQL, XML files and BizData.ini in this %COMMERCE_SERVER_ROOT% directory.

Automating the Unpacking Process

To automate the PUP process you will need an ini file. The ini file is an answer file to pup process and a sample ini can be found under %COMMERCE_SERVER_ROOT%\Sdk\Samples\SiteCreate\CSharpTemplate.ini.

Command line to pack a site:

pup /p /s:BlankSite /f:C:\Program Files\Microsoft Commerce Server 2007\PuP Packages\YourSite.pup
/i:C:\Program Files\Microsoft Commerce Server 2007\PuP Packages \YourSite.ini

Command line to unpack a site:

"C:\Program Files\Microsoft Commerce Server 2007\PuP.exe" /u
/f:C:\Program Files\Microsoft Commerce Server 2007\PuP Packages\CSharp.pup
/i:C:\Commerce\CSharp.ini

For more information and command line option see online help How to Run Site Packager from the Command Line.

Pup Structure

PUP files are Structured Storage. Structured Storage provides file and data persistence in COM by handling a single file as a structured collection of objects known as storages and streams. So PUP.exe generate a Structured Storage file then puts it's site and resource data into it. The Site and Data is further structured inside Cab files. To keep this structure formalized a table of content keeps track of what's inside the PUP file. To create Cab file Cabarc.exe is used under the root of where Commerce Server is installed.

diagram of PUP file structure:

How many PUP files are there?

There are three PUP files that are installed with Commerce Server blank PUP, CSharp PUP and DW PUP.

Blank PUP

This PUP file is used when you generate a Commerce Site using Visual Studio.

CSharp PUP

Generates a blank C# Site.

DW PUP

Data warehouse resource is stored in the PUP file.

PUP Security

You need to be a domain administrator to execute the PUP.exe. Remember the PUP file has the structure of the Commerce Server Systems so it needs to be able to hit SQL and create databases and SQL objects. It also needs to access IIS metabase information and create IIS sites or Virtual Directory. Not to include creating a pup file under the c:\ drive. If I can remember correctly remote PUP support was removed for Commerce Server 2007.

Pre and Post PUP Activities

PUP can launch a script for Pre and Post operations. The script must be in the same directory as the PUP file and must be named Pre<package name>.vbs or Post<package name>.vbs.

Backward Compatibility of PUP files

Backward compatibilty of PUP file are supported but you can read more about it Migration Impact on Pup Files here.

So you should have a good understanding of PUP.exe in the next blog post we will take a deeper dive into PUP. In another words we will flay PUP :).