Registry Functions for Web Forms Applications

PowerBuilder Web Forms applications can read registry entries at the server side and can write registry entries to a registry.xml file.

Searching and setting registry entries

The RegistryGet, RegistryKeys, and RegistryValues functions can search the server registry for registry entries if a registry.xml file does not exist in the applicationName_root/File/Common directory under the IIS virtual root, where applicationName is the name of the current Web Forms application. The registry search functions also search the server registry when the registry.xml file exists but the entries you are searching for are not contained in the current application’s registry.xml file.

The RegistrySet function creates the registry.xml file—if one does not already exist—in the applicationName_root/File/Session/SessionID for the current Web Forms session or in the applicationName_root/File/User/UserName directory when the current user has logged in with a permanent user account. If a registry.xml file already exists, the arguments of the RegistrySet function are added to the contents of the existing registry.xml file.

The RegistrySet function can also copy a registry.xml file from applicationName_root/File/Common to applicationName_root/File/Session/SessionID or to applicationName_root/File/User/UserName, but it writes to the registry.xml file in the SessionID or UserName directory only.

For information about permanent user accounts, see Creating Permanent User Accounts.

Rules for registry searching and setting

These rules apply to registry search and setting operations:

Searches for registry entries, keys, or values are conducted first in the registry.xml file. The search uses the server registry only if the registry entry, key, or value cannot be found in the registry.xml file.
Application users can set or write registry entries only in the registry.xml file in the applicationName_root/File/Session/SessionID folder for the current session or in the applicationName_root/File/User/UserName folder for the current user.
Application users can delete registry keys or values only from the registry.xml file in the SessionID folder for the current session or the UserName folder for the current user.

Deploying a registry.xml file

A text box at the bottom of the Resource Files tab of a Web Forms project allows you to select a registry.xml file for deployment to the applicationName_root/File/Common directory under the virtual root for IIS Web sites. If the Web Forms application searches for a registry entry, key, or value, the registry.xml file is copied to the applicationName_root/File/Session/SessionID folder for the current session or to the applicationName_root/File/User/UserName folder for the current user.

This is sample content of a registry.xml file:

<?xml version="1.0"?>
<RegistryRoot>
  <k name="HKEY_LOCAL_MACHINE">
    <k name="Software">
      <k name="MyApp">
        <k name="Fonts">
          <v name="Title">MyTrueType</v>
        </k>
      </k>
    </k>
  </k>
</RegistryRoot>

The first time the registry function is called, the system copies registry.xml from the Common directory to the SessionID or UserName directory; after that, the system uses the registry.xml copy under the SessionID or UserName directory.