ClickOnce Deployment

Deployment of IFS Enterprise Explorer can be done using the ClickOnce methodology. To achieve this you will make a deployment of the built client files on the middle tier application server, or any web server. You will need to electronically sign the deployment manifest files for the host you use. Once this is done and your web server is running you need to verify that you can start the client as an end user.

Contents

About ClickOnce

ClickOnce applications are fundamentally low impact. Applications are completely self-contained & install per-user, meaning no-admin rights are required. You don’t have to worry about a ClickOnce application breaking other applications.

ClickOnce applications can be deployed via web servers, file servers or CDs. A ClickOnce application can choose to be Installed, meaning it gets start menu & add/remove program entries, or an app can simply be run & cached. ClickOnce has several ways it can be configured to automatically check for application updates. 

ClickOnce applications run in a secure sandbox provided by the .Net Code Access Security model.

When talking about deploying applications over the network, size of the application is important. To help with this, ClickOnce support HTTP compression. ClickOnce applications can also choose to incrementally download themselves. Application files can be marked as optional.

Prerequisites

Using ClickOnce requires that the target client already have the .NET Framework installed. On the server side, ClickOnce needs only an HTTP 1.1 compliant web server or alternatively a file server.

If you are doing a real ClickOnce deployment with a "real" certificate, then you need to generate a Personal inFormation eXchange (PFX) file, a certificate and a private key, which must be obtained from a certificate authority.  Obtain a certificate for ClickOnce deployment

Sign Your Deployment Manifest  with Certificate

ClickOnce deployed applications must be signed with a certificate. Signing the deployment with an Authenticode certificate trusted by all computers in your network is the recommended approach.

Note: This task must be repeated after an upgrade has been installed. It is necessary to use different certificates for different environments without duplicating and signing with the same certificate. If the same certificate is used it may lead to inconsistencies in the download cache on the end user machines.

To sign the deployment manifest files there is a tool called F1Mage.exe (Foundation1 Manifest Generation) available. This tool is located in the IFS Enterprise Explorer runtime directory.

You can run this interactively in a graphical user interface or from command prompt using parameters.

Sign Manifest Using the Graphical User Interface

  1. Locate the Client Runtime folder

    The client runtime folder is located in <ifs_home>\<repository>\client\runtime

  2. Start the F1Mage.exe tool

    At the command prompt type

    > f1mage.exe
     

    Click Advanced to see more options:

  3. Enter the parameters
     
    Parameter Description
    Certificate File
         		 The deployment manifests must be signed with a certificate. The certificate must be intended for code signing. It is recommended to use an Authenticode certificate.
    You can select an existing certificate from file (.pfx) or from your personal certificate store to sign with. This is the recommended way. You can also generate a new test certificate to sign with. This should be seen as a test procedure and should not be used in production environments, since it will prompt the end user with a dialog saying "Unknown Publisher" .
    Deployment Manifest File This should point to the file Ifs.Fnd.Explorer.application in the folder where the deployment files are located.
    Publishing Location Points to the web server or network share where the application is published. Must include the complete path to the deployment manifest file.
    Example http://myserver:58080/client/runtime/Ifs.Fnd.Explorer.application

    or

    file://myserver/mynetworkshare/client/runtime/Ifs.Fnd.Explorer.application
    System name Typical the Instance Name
    Online Application No shortcut will be added to the Microsoft Windows Start Menu. Users starts IFS Enterprise Explorer from a web link (publish location).
    Installed Application A shortcut to the application will be added to the Microsoft Windows Start Menu, and the application can be uninstalled via Add/Remove Programs. The application checks the deployment server for updates before started - just like Online applications (unless you specify differently in Update Options).
  4. If you already have a set of parameters you can load them by clicking Read Installer Output

    This will read the publishing location (such as http://server:port/path) and the system name from a configuration file created by the IFS Installer.


    This is a convenient way to set the manifest properties instead of typing them manually. This button is only enabled if there is a file called server.xml present in the directory from where the tool was started. It will read the configuration file and extract the Publishing Location (web site or network share) and the System name.

  5. Click Sign & Exit.

Sign Manifest Using the Command Line Interface
 

  1. Locate the Client Runtime folder

    The client runtime folder is located in <ifs_home>\repository\client\runtime

  2. Verify the syntax of the command by typing 
    > f1mage.exe /?

Usage: F1Mage CertFile=<file> [Password]=<password> [TimeStampUrl]=<url>
 [DeployUrl]=<url> [SystemName]=<name> FileToSign=<file> [NewCert]
 [ReadConfig] [Installed/Online]
  3. Use the following Command Line Parameters
    Option Description
    /Q Command Line mode. No graphical user interface.
    CertFile Certificate .pfx file intended for code signing and containing a private key.
    Password (Optional) Certificate password.
    TimeStampUrl (Optional) Specifies the address of a server that timestamps your signature. When you provide a certificate, this external site verifies the time that the application was signed. Example: http://timestamp.verisign.com/scripts/timstamp.dll
    DeployUrl (Optional) Change the Deployment Url in the manifest.
    SystemName (Optional) Change the System Name in the manifest.
    FileToSign The Deployment Manifest file to sign.
    Installed (Optional) Mark as a ClickOnce Installed application. (Default is Online)
    Online (Optional) Mark as a ClickOnce Online application. (Default)
    NewCert (Deprecated functionality) (Optional) Create a new test certificate. Must specify a certFile. Implies Quiet mode.
    ReadConfig (Optional) Read configuration data from the Installer (if file system.xml exists). This will override SystemName and DeployUrl parameters. Implies Quiet mode.
  4. Execute your command

    Example:
    f1mage CertFile=mycert.pfx filetosign=Ifs.Fnd.Explorer.application ReadConfig

Deploying to a Linux server

Deploying the application with ClickOnce from a Linux server is possible.

Since signing the deployment manifest is a mandatory step, and this requires Microsoft Windows and Microsoft .Net Framework 4.0 or later, you have to do some manual steps to make the deployment work on a Linux server. F1mage.exe will not run on a Linux machine.

  1. Copy the client runtime folder (<ifs_home>\repository\client\runtime)  to a machine running Windows and the .Net Framework.
  2. Run f1mage in graphical user interface mode or command line mode as described above to sign the manifests.
  3. After this step, copy the folder back to the deployment server.
  4. Run the script pack-and-deploy-client.sh located in <ifs_home>\repository\client.

Deploying to a clustered server

When installing on several nodes of a cluster, only one copy should be signed using the cluster alias URL and then copied to other nodes.

1. Sign the manifest on one node using steps described in Sign Manifest Using the Graphical User Interface or Sign Manifest Using the Command Line Interface
Make sure that the deployment URL is the one that will be used to access the cluster.

2. Copy the signed runtime folder to other nodes.

Satellite Deployment

Satellite deployment means having several ClickOnce deployment sites where all the clients are connecting to the same application server. This can be useful if you have one central application server, but want users to download the client applications from a deployment server near (network wise) their PCs. For example, you have a central server in the UK, but client machines in say Sweden and France. You could then setup two local deployment servers to improve client download performance, while IFS Enterprise Explorer client still logons to the one IFS Applications application server in UK.

To perform a satellite installation:

  1. Start with a normal installation as described above.
  2. Create satellite web servers using standard web server software.
  3. Copy all files in \client\runtime to the satellite web servers.
  4. For each satellite web server: run F1Mage and enter deployment URL pointing to that particular server. 
  5. End users then starts IFS Enterprise Explorer from their local deployment server, but connects to the same application server.

ClickOnce from an end user perspective

You will now verify that the installation works for the end users.

  1. Make sure your Web Server is up and running

    The web server was installed and configured when you created your application server instance. If you followed the instruction the web server is now already started.

     

  2. Start the home page for your IFS Applications instance

    The home page is normally located at the server where you have installed the extended server. The URL for this was presented to you by the installer tool once the installation of your instance was completed. For example https://myserver:58080

    The IFS Applications instance start page

     

  3. Click the link Enterprise Explorer to start the ClickOnce Deployment.

    The Application Launcher presents the Launching Application window.

    Launching Application window

    If the application is not yet configured as trusted, the Launching Application window will be followed by an Application Run Security Warning window.

    To obtain full ClickOnce ability - that the user does not need to make a trust decision the first time using the application, certain requirements needs to be met:

    - The application must deployed from MyComputer, LocalIntranet or TrustedSites. Zones must be configured as Enabled (default) or Authenticode Required.

    - The application must be signed with a trusted publisher certificate; a X.509 version 3 certificate with extended key usage properties Code Signing (codeSigning) and Microsoft Authenticode (msCodeCom). This certificate needs to be in the Trusted Publishers certificate store.

    - The trusted publisher certificate needs to be signed by a Certificate Authority with a X.509 version 3 certificate with basic constraint CA:TRUE. This certificate should be in Intermediate Certification Authorities or Trusted Root Certification Authorities certificate store.

    If the deployment has been signed with a trusted certificate ( Obtain a certificate for ClickOnce deployment  ) which is not listed as a Trusted Publisher, a yellow warning sign will be shown.  If you click the More Information... link, it will show the Application Run More Information window, stating that the application requires machine access.

    Application Run Security Warning (yellow) window
     

    Application Run More Information (Machine Access) window


     

    The 'Unknown publisher' message in the ClickOnce information dialog is displayed when the certificate used to sign the ClickOnce manifests is not a trusted certificate. In order to be trusted, a certificate must chain to a trusted root certificate authority, and the test certificates created by f1mage.exe "Generate New" are not trusted by default.
     

    Application Run Security Warning (red) window


    Application Run More Information (Publisher, Machine Access) window

  4. Click Run to continue to launch Enterprise Explorer.

    Downloading of the application starts.

    Downloading in progress
     

  5. Login to IFS Applications

    After initial download, IFS Applications will automatically start.

    This is the IFS Applications logon dialog.

Verify

If the logon dialog shows correctly you have managed to get the deployment and signing ok.

To verify on-demand loading of features you need to logon as a valid user and select a feature from the navigator. As the feature is loaded from the server for the first time it will display a progress bar. The feature is cached on the client. New deployment of client files on the server will be detected at later logon.
Problem: Nothing happens when you use the link on the start web page!

The IFS Applications instance start page

Resolution: In Internet Explorer, open Tools->Internet Options. On the Security Tab, select the zone (typical Local Intranet) where the web page is located and then click Custom Level. Make sure settings under ".Net Framework-reliant components" are set to Enable "Run components..."

  

 

Internet Explorer Security settings for .Net components
 

Problem: Errors when starting the application.

An error occurs when you start the application, either from the web page or from the Start Menu shortcut

Analysis: This is most likely caused by an update of the application files on the server, without rebuilding and resigning the application manifests
Resolution: re-sign the manifest using the sign tool f1mage.exe as described above.

If the error Details shows as below:

ERROR SUMMARY
Below is a summary of the errors, details of these errors are listed later in the log.
* Activation of http://lkpgseapp57.corpnet.ifsworld.com:58080/client/runtime/Ifs.Fnd.Explorer.application  resulted in exception. Following failure messages were detected:
+ Downloading http://lkpgseapp57.corpnet.ifsworld.com:58080/client/runtime/Ifs.Fnd.Explorer.exe.config did not succeed.
+ The remote server returned an error: (404) Not Found.

there is a problem with the web server blocking this file from being downloaded. By default Microsoft IIS does not allow download of .config files.

Configure your server to unblock any restricted file extensions used by the application, such as .exe, .dll, .config., .manifest, .application. For more details see ClickOnce FAQ.


One way of allowing the .config file to be downloaded is to use this web.config file at the root of your web share folder:

<configuration>
  <system.web>
    <!--
    Remove the *.config handler so that we_can serve up
    *.exe.config files, but make it forbidden to serve up the
    web.config file itself.
    -->
    <httpHandlers>
      <remove verb="*" path="*.config" />
      <add verb="*" path="web.config"
              type="System.Web.HttpForbiddenHandler"/>
    </httpHandlers>
  </system.web>
</configuration>
Problem: Error when starting an Online application from the publishing location.

Analysis: The System Administrator chooses to deploy the application as an Installed application and end users installs the application and runs for a period of time. The System Administrator then chooses to change the deployment setup to use Online mode. End users having the application installed now tries to run the Online application from the publishing location. This will fail, unless the end user first uninstalls the application using Add/Remove Programs in Control Panel .

Problem: Link IFS Applications - <Instance Name> exists in start page but do not execute.

Analysis: In Windows 2003 Server, IE runs Enhanced Security settings as default and the setting "Display enhanced security configuration dialog" is NOT Enabled. This means that end users will get no warning on "Trusted sites".

Resolution: Enable "Display enhanced security configuration dialog" OR add the site as a “Trusted site"

Problem: When you click Create Test Certificate, a dialog pops up asking for a Password/Confirm Password.

A dialog pops up asking for a password when you click on the "Create Test Certificate"

Analysis: This is a result of a Microsoft introduced bug in cryptAPIs which forced us to use external SDK tool makecert.exe to create test certificates. Unfortunately makecert.exe being a command line tool, shows this UI and there is no way to suppress it and go with a blank password.

Resolution: Click on None leaving Password/Confirm Password fields blank. When you click Sign & Exit another dialog will pop up asking you to enter password to open the created test certificate file. This should also be kept blank and click OK.

A dialog pops up asking to enter password to open the created test certificate.
Problem: Errors occur if you have the same deployment “IFS Enterprise Explorer 1.x” installed on two different publish locations and run them side by side which are signed with the same certificate.

Analysis: This problem will occur if you have the same deployment “IFS Enterprise Explorer 1.x” installed on two different publish locations and run them side by side. If the same certificate is used it may lead to inconsistencies in the download cache on the end user machines. The second deployment, when started (downloading) overwrites parts of the first deployment.

Resolution: It is necessary to use different certificates for different environments without duplicating and signing with the same certificate.
 

Problem: Error occurs when trying to Sign & Exit with a certificate signed by your own Certificate Authority.

An error occurs when signing with a certificate signed by your own Certificate Authority

Analysis: If you want to use a certificate signed by your own Certificate Authority, the Certificate Authority must be added to the Trusted Root Certification Authorities on the target computer. Else this error message is shown.

Resolution: Add the Certification Authority to Trusted Root Certification Authorities on the target computer using the Certificate Manager Tool (Certmgr.exe).