Testing a Zip Package for Inclusion with the Web Application Gallery

by Mai-lan Tomsen Bukovec

Note

The Windows Web Application Gallery (WWAG) is being retired on July 1, 2021. We are no longer taking submissions via the Submission Portal. Please contact webpi@microsoft.com to make updates to your existing submission.

The Web Application Gallery makes it easy for Windows users to find and deploy a free open source, community application onto a computer running Windows XP or later. To learn more about how to build Web Deploy support for a zip package so that the application can be included in the Web Application Gallery, read the Package An Application for the Web Application Gallery guide or view the Adding Web Deployment Tool Support to Community Application ZIP Packages videocast. Once you have build Web Application Gallery integration for your zip package, you can test the Web Application Integration using Web Platform Installer.

Both the Web Application Gallery and the Web Platform Installer consume the same application and product feeds. The Web Platform Installer also orchestrates every deployment from the Web Application Gallery. As a result, you can test the deployment experience from the Web Application Gallery by using the Web Platform Installer and local feeds modified to contain the location of the application package that you want to test. Once you get done with the application testing, you can submit your application link to the Web Application Gallery team on the Web Application Gallery developers site.

You can take two different approaches to test your application package in your computer:

  1. Modify a local copy of the live xml feeds. You may want to use this approach if:

    • You have already published your application in the Web Application Gallery, and
    • You only need to modify a few fields in the feed xml (installer url, version, and sha-1 hash), and
    • You want to test a new updated package of your application following the end-to-end user experience that your users will see when using the Web Platform Installer.
  2. Create a custom feed. You may want to use this approach if:

    • You want to build and maintain your own custom feed file.
    • You want to avoid making changes to the feeds that will drive all of the Web Platform Installation.

Details for each of the two approaches follow.

Test by modifying a local copy of the live XML feeds

To test your application package locally by modifying a copy of the live XML feed files, follow these steps:

Step 1. Download the Web Platform Installer

The Web Platform Installer orchestrates the installation of applications from the Web Application Gallery, and is the tool you use to validate local feeds with your modified zip package. You can down the Web Platform Installer from: https://www.iis.net/extensions/webpi.If you already have Web Platform Installer installed, please make sure it is the latest version of Web Platform Installer.

Download the two WebPI feeds to your computer:

Step 3. Make Sure the Local XML Feeds Can Talk to Each Other

In the WebProductList.xml feed, look for the reference to WebApplicationList.xml. Change the location to point the location that you installed WebApplicationList.xml on your local computer.

Example:
<link rel="enclosure" href="file:///C:/wag/WebApplicationList.xml" />

Save the change.

Step 4. Modify the Local WebApplicationList.XML Feed to Point to the New Application Package

Next, you'll have to modify the WebApplicationList.xml to point to your new zip package xml file for testing. You will be eidting the XML entry for an application that would be similar to yours or, if your package is already included in the Web Application Gallery, the XML entry for your existing application.

When you find "<productId>SimilarApp</productId>", you will see a child <entry type="application"> element. Within this element,look for the <installerURL> element.

Example
<installerURL>http://site.org/app1.0.zip</installerURL>

Change the location within that element to point to your local application zip package.

Example
<installerURL>file://C:/wag/app1.0.zip</installerURL>

You will also need to find the <sha1> element and change it to the new hash value or remove it. If you forget this step, your application testing will fail based on mismatched hash values.
Save the changes.

Step 5. Set Up the Test Environment with Dependencies

When a user installs an application from the Web Application Gallery, the Web Platform Installer will check the user's machine for application dependencies. If the user's machine is missing an application dependency, such as FastCGI for PHP applications, Web Platform Installer will take care of installing those dependencies. However, the Web Platform Installer test feed configuration does not support application dependency installations; the test feed configuration assumes all dependencies are present.

As a result, when you are testing your application install in a clean machine, you will have to install application dependencies yourself. There are two ways to simplify the installation of application dependencies in your test feed environment:

  1. You can use the Web Platform Installer to install Internet Information Services (IIS), FastCGI 1.0, Web Deployment Tool 1.0, and other dependencies for your application like SQL Express.
  2. You can install a similar application from Web Platform Installer or Web Application Gallery. For example, if you are testing a PHP application and want to set up a clean machine with the right dependencies, you can install another PHP application from the Web Application Gallery. That installation process will automatically install and configure the right dependencies on your computer for PHP application testing.

Once you have the test environment configured, you are ready to run Web Platform Installer against your local modified feed.

Step 6. Run Web Platform Installer Against Local Feed

Follow these steps so that Web Platform Installer will point to the local feed when it loads:

  • Click on Start -> Run

  • Type 'regedit' and Click OK

  • Under HKEY_LOCAL_MACHINE\Software\Microsoft\Webplatforminstaller, add a string key "ProductXmlLocation" and let it point to the local copy of Webproductlist.xml

  • Close any instances of Web Platform Installer

  • Launch Web Platform Installer

  • Click on 'Options' to select IIS or IIS Express (Web Matrix) and Click OK

  • Look for the application you are testing and Click on Add

  • Click on Install

    Web Platform Installer will now install the test application package onto IIS or Web Matrix.

Test by creating a custom feed

To test your application package locally by modifying a copy of the live XML feed files, follow these steps (for more details see: https://blogs.iis.net/kateroh/archive/2009/10/24/web-pi-extensibility-custom-feeds-installing-custom-products.aspx):

Step 1. Create a new custom feed XML file

Use the example below to create the custom feed XML file. This example illustrates:

  • How to add applications with ASP.NET/SQL and PHP/MySql dependencies,
  • Create a new tab and subtabs based on keywords,
  • Group products together and hint Web PI that your product is available in different languages.

Notice that you have to define a new custom tab for your custom products, since they cannot to be added to Web PI core tabs.

<?xml version="1.0" encoding="utf-8"?>

<feed xmlns="http://www.w3.org/2005/Atom">
  <version>1.0.0</version>
  <title>Sample Applications for WebPI v2 RTW Feed</title>
  <link href="http://www.contoso.com/SampleApplicationsFeed.xml" />
  <updated>2009-10-5T16:30:00Z</updated>
  <author>
    <name>Sample Application Builder</name>
    <uri>http://www.contoso.com/</uri>
  </author>
  <id>http://www.contoso.com/SampleApplicationsFeed.xml</id>

  <!-- Sample ASP.NET & SQL app with dependencies -->
  <entry type="application">
    <productId>Sample_ASPNET_SQL_App</productId>
    <title>Sample ASP.NET and SQL application</title>
    <summary>ASP.NET and SQL application sample</summary>
    <longSummary>Sample ASP.NET and SQL to show how to add a feed with a custom ASP.NET application to WebPI and define all dependencies.</longSummary>

    <!-- Defines grouping for the application based on the keyword(s) -->
    <keywords>
      <keywordId>ASPNETApps</keywordId>	<keywordId>SQL</keywordId>
    </keywords>

    <version>1.0</version>
    <images>
      <icon>c:\SampleASPNETAppIcon.jpg</icon>
    </images>
    
    <updated>2009-10-5T18:30:02Z</updated>
    <published>2009-10-5T18:30:02Z</published>

    <author>
      <name>Sample Application Builder</name>
      <uri>http://www.contoso.com</uri>
    </author>
    
    <!-- Bring along SQLExpress, if it is not installed as a related/nice-to-have product, not a dependency -->
    <related>
      <relatedProduct>
        <productId>SQLExpress</productId>
      </relatedProduct>
    </related>

    <!-- 
         Minimum set of requirements/dependencies in order to successfully install the application: 
         WDeploy, SQL Management Objects and URL Rewrite.
    -->
    <dependency>
      <and>
        <dependency>
          <productId>SMO</productId>
        </dependency>
        <dependency>
          <productId>WDeployNoSMO</productId>
        </dependency>
        <dependency>
          <productId>UrlRewrite2</productId>
        </dependency>
      </and>
    </dependency>
     
    <!-- Installer for an application should be Web Deploy package -->
    <installers>
      <installer>
        <id>1</id>
        <!-- List of languages this package is localized in: English, Korean, Spanish, Traditional and Simplified Chinese -->
        <languageId>en</languageId>
        <languageId>ko</languageId>
        <languageId>es</languageId>
        <languageId>zh-tw</languageId>
        <languageId>zh-cn</languageId>

        <installerFile>
          <!-- size of the package in KBs -->
          <fileSize>1024</fileSize>
          <installerURL>http://www.contoso.com/SampleASPNETApplication.zip</installerURL>
          <displayURL>http://www.contoso.com/SampleASPNETApplication.aspx</displayURL>
          <!-- SHA of the package file for signature verification -->
          <sha1>1223334444555556666667777777888888889999</sha1>
        </installerFile>
        <helpLink>http://www.contoso.com/SampleASPNETApplicationForum.aspx</helpLink>
        <msDeploy>
          <startPage>
            <!-- start with a setup page rather than a default one -->
            <startPage>Setup.aspx</startPage>
          </startPage>
        </msDeploy>
      </installer>
    </installers>
  </entry>

  <!-- Sample PHP & MySQL app with dependencies -->
  <entry type="application">
    <productId>Sample_PHP_MySQL_App</productId>
    <title>Sample PHP and MySQL application</title>
    <summary>PHP and MySQL application sample</summary>
    <longSummary>Sample PHP and MySQL to show how to add a feed with a custom PHP application to WebPI and define all dependencies.</longSummary>

    <!-- Display under PHPApps keyword subtab -->
    <keywords>
      <keywordId>PHPApps</keywordId>
      <keywordId>MySQL</keywordId>
    </keywords>

    <version>1.0</version>
    <images>
      <icon>c:\SamplePHPAppIcon.jpg</icon>
    </images>

    <updated>2009-10-5T18:30:02Z</updated>
    <published>2009-10-5T18:30:02Z</published>

    <author>
      <name>Sample Application Builder</name>
      <uri>http://www.contoso.com</uri>
    </author>

    <!-- Bring along SQLExpress, if it is not installed as a related/nice-to-have product, not a dependency -->
    <related>
      <relatedProduct>
        <productId>MySQL</productId>
      </relatedProduct>
    </related>

    <!-- 
         Minimum set of requirements/dependencies in order to successfully install the application: 
         PHP, WDeploy, SQL Management Objects, MySql Connector and URL Rewrite.
     -->
    <dependency>
      <and>
        <dependency>
          <productId>WDeployNoSMO</productId>
        </dependency>
        <dependency>
          <productId>PHP53</productId>
        </dependency>
        <dependency>
          <productId>MySQLConnector</productId>
        </dependency>
        <dependency>
          <productId>UrlRewrite2</productId>
        </dependency>
      </and>
    </dependency>
    
    <!-- Installer for an application should be Web Deploy package -->
    <installers>
      <installer>
        <id>1</id>
        <!-- List of languages this package is localized in: English, Russian, French, German and Italian -->
        <languageId>en</languageId>
        <languageId>ru</languageId>
        <languageId>fr</languageId>
        <languageId>de</languageId>
        <languageId>it</languageId>
        
        <installerFile>
          <!-- size of the package in KBs -->
          <fileSize>1024</fileSize>
          <installerURL>http://www.contoso.com/SamplePHPApplication.zip</installerURL>
          <displayURL>http://www.contoso.com/SamplePHPApplication.aspx</displayURL>
          <!-- SHA of the package file for signature verification -->
          <sha1>1223334444555556666667777777888888889999</sha1>
        </installerFile>
        <helpLink>http://www.contoso.com/SamplePHPApplicationForum.aspx</helpLink>
        <msDeploy>
          <!-- Default page is a start page -->
          <startPage />
        </msDeploy>
      </installer>
    </installers>
  </entry>
  
  <!-- Tab definition -->
  <tabs>
    <tab>
      <keywordTab>
        <id>SampleApplications</id>
        <name>Sample Applications</name>
        <description>Select from sample applications:</description>
        
        <!-- Subtabs definitions -->
        <keywords>
          <keywordId>ASPNETApps</keywordId>
          <keywordId>PHPApps</keywordId>
        </keywords>
      </keywordTab>
    </tab>
  </tabs>

  <!-- Keyword/titles of subtabs to group apps with those keywords under -->
  <keywords>
    <keyword id="ASPNETApps">ASP.NET Apps</keyword>
    <keyword id="PHPApps">PHP Apps</keyword>
  </keywords>
</feed>

You can delete the <entry type="application"> element that do not correspond to the type of application you are interested in. Also, if you have already published your application in the Application gallery, you could copy your application's <entry type="application"> from the live feed: https://www.microsoft.com/web/webpi/4.2/WebApplicationList.xml.

Notice how applications are grouped based on keywords: xml element <keywords>.

Step 2. Enter the Installer URL for your zip package

In the custom feed file, locate the <installerURL> element and provide the path for your zip package, if it in located in the local file system use "file://" instead of "http://"

Example
<installerURL>file://C:/wag/app1.0.zip</installerURL>

Step 3. Enter the new SHA-1 hash

In the custom feed file, locate <sha1> and substitute the value for the corresponding hash for your zip package. You can get a hash of your zip package, by using a free utility called File Checksum Integrity Verifier (FCIV) and running fciv.exe -sha <path to your zip package> from the command prompt.

Step 4. Test your custom feed file

Now, you can try the custom feed file by saving it locally or storing it in a web server, and opening the Options dialog and adding a feed through either a physical path or URL.

Screenshot of the Change Options Window.

Screenshot of Change Options Window under Display Additional Scenarios removes sample X M L.

You should be able to click in the new tab and see your application in it.

Screenshot of Web Platform Installer displaying Sample Applications tab.

Screenshot of Sample Applications tab with chosen application highlighted.

From here you can select your application and proceed with the installation.