About App-V 5.1 dynamic configuration

With dynamic configuration, you can edit the dynamic configuration file to customize how an App-V 5.1 package runs for a user or group. Package customization removes the need to resequence packages using the desired settings. It also provides a way to keep package content and custom settings independent.

Virtual application packages contain a manifest that provides all the core information for the package. This information includes the defaults for the package settings and determines settings in the most basic form (with no additional customization).

When a package gets created, the sequencer generates default deployment and user configuration .xml files automatically using the package manifest data. Therefore, these generated files reflect the default settings configured during sequencing. If you apply these files to a package in the form generated by the sequencer, the packages have the same default settings that came from their manifest.

Use these generated files to make changes, if necessary, which doesn’t directly affect the package. If you want to add, delete or update the configuration files, make your changes about the default values in the manifest information.

Tip

The order in which the files read are:

  • UserConfig.xml
  • DeploymentConfig.xml
  • Manifest

The first entry represents what gets read last. Therefore, its content takes precedence, and all packages inherently contain and provide default settings from the package manifest.

  1. If customizing the DeploymentConfig.xml file and apply the customized settings, the default settings in the package manifest get overridden.
  2. If customizing the UserConfig.xml and apply the customized settings, the default settings for both the deployment configuration and the package manifest get overridden.

User configuration file contents (UserConfig.xml)

The UserConfig file provides configuration settings that get applied for a specific user when deploying the package to a computer running the App-V 5.1 client. These settings don’t affect any other users on the client.

Use the UserConfig file to specify or modify custom settings for a package:

  • Extensions integrated into the native system per user: shortcuts, file-type associations, URL protocols, AppPaths, software clients and COM
  • Virtual subsystems: application objects, environment variables, registry modifications, services and fonts
  • Scripts (user context only)
  • Managing authority (for controlling co-existence of package with App-V 4.6)

The header of a dynamic user configuration file looks like:

<?xml version="1.0" encoding="utf-8"?><UserConfiguration PackageId="1f8488bf-2257-46b4-b27f-09c9dbaae707" DisplayName="Reserved" xmlns="http://schemas.microsoft.com/appv/2010/userconfiguration">

The PackageId is the same value as exists in the manifest file.

Body

The body of the dynamic user configuration file can include all the app extension points defined in the manifest file, as well as information to configure virtual applications. There are four subsections allowed in the body:

  1. Applications
  2. Subsystems
  3. UserScripts
  4. ManagingAuthority

Applications

All app-extensions contained in the manifest file within a package have an Application ID assigned, which you find in the manifest file. The Application ID lets you enable or disable all extensions for a given application within a package. The Application ID must exist in the manifest file, or it gets ignored.

<UserConfiguration PackageId="1f8488bf-2257-46b4-b27f-09c9dbaae707" DisplayName="Reserved"  xmlns="http://schemas.microsoft.com/appv/2010/userconfiguration">

<Applications>

<!--No new application can be defined in policy. AppV Client will ignore any application ID that is not also in the Manifest file-->

<Application Id="{a56fa627-c35f-4a01-9e79-7d36aed8225a}" Enabled="false">

</Application>

</Applications>

..

</UserConfiguration>

Subsystems

AppExtensions and other subsystems arranged as subnodes.

<UserConfiguration PackageId="1f8488bf-2257-46b4-b27f-09c9dbaae707" DisplayName="Reserved" xmlns="http://schemas.microsoft.com/appv/2010/userconfiguration">

<Subsystems>

..

</Subsystems>

..

</UserConfiguration>

You can enable or disable each subsystem using the Enabled attribute.

Extensions

Some subsystems (extension subsystems) control extensions. Those subsystems are Shortcuts, File-Type associations, URL Protocols, AppPaths, Software Clients, and COM.

Extension subsystems can be enabled and disabled independently of the content. For example, if you enable Shortcuts, the client uses the Shortcuts contained within the manifest by default. Each extension subsystem can contain an <Extensions> node. If this child element is present, the client ignores the content in the manifest file for that subsystem and only use the content in the configuration file.

Examples:

  • If you define this in either the user or deployment config file, the content in the manifest gets ignored.

    
    <Shortcuts  Enabled="true"\>
    
    <Extensions>
    
    ...
    
    </Extensions>
    
    </Shortcuts>
    
  • If you define only the following, the content in the manifest gets integrated during publishing.

    
    <Shortcuts  Enabled="true"/>
    
  • If you define the following, all Shortcuts within the manifest still get ignored. In other words, no Shortcuts get integrated.

    
    <Shortcuts  Enabled="true">
    
       <Extensions/>
    
    </Shortcuts>
    

Supported extension subsystems:

Shortcuts extension subsystem controls what shortcuts get integrated into the local system.


<Subsystems>

<Shortcuts Enabled="true">

  <Extensions>

    <Extension Category="AppV.Shortcut">

      <Shortcut>

        <File>[{Common Programs}]\Microsoft Contoso\Microsoft ContosoApp Filler 2010.lnk</File>

        <Target>[{PackageRoot}]\Contoso\ContosoApp.EXE</Target>


      <Icon>[{Windows}]\Installer\{90140000-0011-0000-0000-0000000FF1CE}\inficon.exe</Icon>

        <Arguments />

        <WorkingDirectory />

        <AppUserModelId>ContosoApp.Filler.3</AppUserModelId>

        <Description>Fill out dynamic forms to gather and reuse information throughout the organization using Microsoft ContosoApp.</Description>

        <Hotkey>0</Hotkey>

        <ShowCommand>1</ShowCommand>

      <ApplicationId>[{PackageRoot}]\Contoso\ContosoApp.EXE</ApplicationId>

      </Shortcut>

  </Extension>

  <Extension Category="AppV.Shortcut">

    <Shortcut>

    <File>[{AppData}]\Microsoft\Contoso\Recent\Templates.LNK</File>

      <Target>[{AppData}]\Microsoft\Templates</Target>

      <Icon />

      <Arguments />

      <WorkingDirectory />

      <AppUserModelId />

      <Description />

      <Hotkey>0</Hotkey>

      <ShowCommand>1</ShowCommand>

      <!-- Note the ApplicationId is optional -->

    </Shortcut>

  </Extension>

 </Extensions>

</Shortcuts>

File-Type Associates extension subsystem associates file types with programs to open by default as well as set up the context menu.

Tip

You can set up the subsystem with MIME types.


<FileTypeAssociations Enabled="true">

<Extensions>

  <Extension Category="AppV.FileTypeAssociation">

    <FileTypeAssociation>

      <FileExtension MimeAssociation="true">

      <Name>.docm</Name>

      <ProgId>contosowordpad.DocumentMacroEnabled.12</ProgId>

      <PerceivedType>document</PerceivedType>

    <ContentType>application/vnd.ms-contosowordpad.document.macroEnabled.12</ContentType>

      <OpenWithList>

        <ApplicationName>wincontosowordpad.exe</ApplicationName>

      </OpenWithList>

     <OpenWithProgIds>

        <ProgId>contosowordpad.8</ProgId>

      </OpenWithProgIds>

      <ShellNew>

        <Command />

        <DataBinary />

        <DataText />

        <FileName />

        <NullFile>true</NullFile>

        <ItemName />

        <IconPath />

        <MenuText />

        <Handler />

      </ShellNew>

    </FileExtension>

    <ProgId>

       <Name>contosowordpad.DocumentMacroEnabled.12</Name>

      <DefaultIcon\>[{Windows}]\Installer\{90140000-0011-0000-0000-000000FF1CE}\contosowordpadicon.exe,15</DefaultIcon>

        <Description>Blah Blah Blah</Description>

        <FriendlyTypeName>[{FOLDERID_ProgramFilesX86}]\Microsoft Contoso 14\res.dll,9182</FriendlyTypeName>

        <InfoTip>[{FOLDERID_ProgramFilesX86}]\Microsoft Contoso 14\res.dll,1424</InfoTip>

        <EditFlags>0</EditFlags>

        <ShellCommands>

          <DefaultCommand>Open</DefaultCommand>

          <ShellCommand>

           <ApplicationId>{e56fa627-c35f-4a01-9e79-7d36aed8225a}</ApplicationId>

             <Name>Edit</Name>

             <FriendlyName>&Edit</FriendlyName>

           <CommandLine>"[{PackageRoot}]\Contoso\WINcontosowordpad.EXE" /vu "%1"</CommandLine>

          </ShellCommand>

          </ShellCommand>

          <ApplicationId>{e56fa627-c35f-4a01-9e79-7d36aed8225a}</ApplicationId>

            <Name>Open</Name>

            <FriendlyName>&Open</FriendlyName>

            <CommandLine>"[{PackageRoot}]\Contoso\WINcontosowordpad.EXE" /n "%1"</CommandLine>

            <DropTargetClassId />

            <DdeExec>

              <Application>mscontosowordpad</Application>

              <Topic>ShellSystem</Topic>

              <IfExec>[SHELLNOOP]</IfExec>

              <DdeCommand>[SetForeground][ShellNewDatabase"%1"]</DdeCommand>

            </DdeExec>

          </ShellCommand>

        </ShellCommands>

      </ProgId>

     </FileTypeAssociation>

   </Extension>

  </Extensions>

  </FileTypeAssociations>

URL Protocols extension subsystem controls the URL protocols integrated into the local registry of the client machine, for example, mailto:.


<URLProtocols Enabled="true">

<Extensions>

<Extension Category="AppV.URLProtocol">

<URLProtocol>

  <Name>mailto</Name>

  <ApplicationURLProtocol>

  <DefaultIcon>[{ProgramFilesX86}]\MicrosoftContoso\Contoso\contosomail.EXE,-9403</DefaultIcon>

  <EditFlags>2</EditFlags>

  <Description />

  <AppUserModelId />

  <FriendlyTypeName />

  <InfoTip />

<SourceFilter />

  <ShellFolder />

  <WebNavigableCLSID />

  <ExplorerFlags>2</ExplorerFlags>

  <CLSID />

  <ShellCommands>

  <DefaultCommand>open</DefaultCommand>

  <ShellCommand>

  <ApplicationId>[{ProgramFilesX86}]\Microsoft Contoso\Contoso\contosomail.EXE</ApplicationId>

  <Name>open</Name>

  <CommandLine>[{ProgramFilesX86}\Microsoft Contoso\Contoso\contosomail.EXE" -c OEP.Note /m "%1"</CommandLine>

  <DropTargetClassId />

  <FriendlyName />

  <Extended>0</Extended>

  <LegacyDisable>0</LegacyDisable>

  <SuppressionPolicy>2</SuppressionPolicy>

   <DdeExec>

  <NoActivateHandler />

  <Application>contosomail</Application>

  <Topic>ShellSystem</Topic>

  <IfExec>[SHELLNOOP]</IfExec>

  <DdeCommand>[SetForeground][ShellNewDatabase "%1"]</DdeCommand>

  </DdeExec>

  </ShellCommand>

  </ShellCommands>

  </ApplicationURLProtocol>

  </URLProtocol>

  </Extension>

  </Extension>

  </URLProtocols>

Software Clients extension subsystem allows the app to register as an email client, news reader, media player and makes the app visible in the Set program access and Computer defaults UI. In most cases, you should only need to enable and disable it. There is also a control to enable and disable the email client specifically if you want the other clients still enabled except for that client.


<SoftwareClients Enabled="true">

  <ClientConfiguration EmailEnabled="false" />

</SoftwareClients>

AppPaths extension subsystem opens apps registered with an application path. For example, if contoso.exe has an apppath name of myapp, users can type myapp from the run menu, opening contoso.exe.


<AppPaths Enabled="true">

<Extensions>

<Extension Category="AppV.AppPath">

<AppPath>

  <ApplicationId>[{ProgramFilesX86}]\Microsoft Contoso\Contoso\contosomail.EXE</ApplicationId>

  <Name>contosomail.exe</Name>

  <ApplicationPath>[{ProgramFilesX86}]\Microsoft Contoso\Contoso\contosomail.EXE</ApplicationPath>

  <PATHEnvironmentVariablePrefix />

  <CanAcceptUrl>false</CanAcceptUrl>

  <SaveUrl />

</AppPath>

</Extension>

</Extensions>

</AppPaths>

COM extensions subsystem allows an application registered to local COM servers. The mode can be:

  • Integration
  • Isolated
  • Off

<COM Mode="Isolated"/>

Virtual Kernel Objects


<Objects Enabled="false" />

Virtual Registry sets a registry in the virtual registry within HKCU.


<Registry Enabled="true">

<Include>

<Key Path="\REGISTRY\USER\[{AppVCurrentUserSID}]\Software\ABC">

<Value Type="REG_SZ" Name="Bar" Data="NewValue" />

 </Key>

  <Key Path="\REGISTRY\USER\[{AppVCurrentUserSID}]\Software\EmptyKey" />

 </Include>

<Delete>

</Registry>

Virtual File System


    <FileSystem Enabled="true" />

Virtual Fonts


      <Fonts Enabled="false" />

Virtual Environment Variables


<EnvironmentVariables Enabled="true">

<Include>

       <Variable Name="UserPath" Value="%path%;%UserProfile%" />

       <Variable Name="UserLib" Value="%UserProfile%\ABC" />

       </Include>

      <Delete>

       <Variable Name="lib" />

        </Delete>

        </EnvironmentVariables>

Virtual services


      <Services Enabled="false" />

UserScripts

Use UserScripts to set up or alter the virtual environment. You can also execute scripts at the time of deployment or to clean up the environment after the application terminates. To see a sample script, refer to the user configuration file generated by the sequencer. The Scripts section below provides more information on the various triggers that can be used.

ManagingAuthority

Use ManagingAuthority when two versions of your package co-exist on the same machine, one deployed to App-V 4.6 and another deployed on App-V 5.0. To allow App-V vNext to take over App-V 4.6 extension points for the named package enter the following in the UserConfig file (where PackageName is the Package GUID in App-V 4.6:


<ManagingAuthority TakeoverExtensionPointsFrom46="true" PackageName="032630c0-b8e2-417c-acef-76fc5297fe81" />

Deployment configuration file (DeploymentConfig.xml)

The DeploymentConfig file provides configuration settings for machine context and user context, providing the same capabilities listed in the UserConfig file. The setting get applied when deploying the package to a computer running the App-V 5.1 client.

Use the DeploymentConfig file to specify or modify custom settings for a package:

  • All UserConfig settings
  • Extensions that can only be applied globally for all users
  • Virtual subsystems for global machine locations, for example, registry
  • Product source URL
  • Scripts (machine context only)
  • Controls to terminate child processes

Header

The header of a dynamic deployment configuration file looks like:

<?xml version="1.0" encoding="utf-8"?><DeploymentConfiguration PackageId="1f8488bf-2257-46b4-b27f-09c9dbaae707" DisplayName="Reserved" xmlns="http://schemas.microsoft.com/appv/2010/deploymentconfiguration">

The PackageId is the same value as exists in the manifest file.

Body

The body of the dynamic deployment configuration file includes two sections:

  • UserConfiguration: allows the same content as the user configuration file described in the previous section. When publishing the package to a user, any appextensions configuration settings in this section override corresponding settings in the manifest within the package, unless you provide a user configuration file. If also providing a UserConfig file, it gets used instead of the User settings in the deployment configuration file. If publishing the package globally, then only the contents of the deployment configuration file get used in combination with the manifest. For more details, see User configuration file contents (UserConfig.xml).

  • MachineConfiguration: contains information that can be configured only for an entire machine, not for a specific user on the machine. For example, HKEY_LOCAL_MACHINE registry keys in the VFS.


<DeploymentConfiguration PackageId="1f8488bf-2257-46b4-b27f-09c9dbaae707" DisplayName="Reserved" xmlns="http://schemas.microsoft.com/appv/2010/deploymentconfiguration">

<UserConfiguration>

...

</UserConfiguration>

<MachineConfiguration>

...

</MachineConfiguration>

...

</MachineConfiguration>

</DeploymentConfiguration>

UserConfiguration

Refer to User configuration file contents (UserConfig.xml) for information on the settings provided for this section.

MachineConfiguration

Use the MachineConfiguration section to configure information for an entire machine; not for a specific user on the computer. For example, HKEY_LOCAL_MACHINE registry keys in the virtual registry. There are four subsections allowed in under this element:

  1. Subsystems
  2. ProductSourceURLOptOut
  3. MachineScripts
  4. TerminateChildProcess

Subsystems

AppExtensions and other subsystems arranged as subnodes.


<MachineConfiguration>

  <Subsystems>

  …

  </Subsystems>

…

</MachineConfiguration>

You can enable or disable each subsystem using the Enabled attribute.

Extensions

Some subsystems (extension subsystems) control extensions. The subsystem is Application Capabilities that default programs use. For this type of extension, the package must be published globally for integration into the local system. The same rules for controls and settings that apply to the Extensions in the User Configuration also, apply to those in the MachineConfiguration section.

Application Capabilities: Used by default programs that allow an application to register itself as:

  • Capable of opening specific file extensions
  • A contender for the start menu internet browser slot
  • Capable of opening specific windows MIME types

This extension also makes the virtual application visible in the Set default programs UI.


<ApplicationCapabilities Enabled="true">

  <Extensions>

   <Extension Category="AppV.ApplicationCapabilities">

    <ApplicationCapabilities>


   <ApplicationId>[{PackageRoot}]\LitView\LitViewBrowser.exe</ApplicationId>

     <Reference>

      <Name>LitView Browser</Name>

      <Path>SOFTWARE\LitView\Browser\Capabilities</Path>

     </Reference>

   <CapabilityGroup>

    <Capabilities>


   <Name>@[{ProgramFilesX86}]\LitView\LitViewBrowser.exe,-12345</Name>


   <Description>@[{ProgramFilesX86}]\LitView\LitViewBrowser.exe,-12346</Description>

     <Hidden>0</Hidden>

     <EMailSoftwareClient>Lit View E-Mail Client</EMailSoftwareClient>

     <FileAssociationList>

      <FileAssociation Extension=".htm" ProgID="LitViewHTML" />

      <FileAssociation Extension=".html" ProgID="LitViewHTML" />

      <FileAssociation Extension=".shtml" ProgID="LitViewHTML" />

     </FileAssociationList>

     <MIMEAssociationList>

      <MIMEAssociation Type="audio/mp3" ProgID="LitViewHTML" />

      <MIMEAssociation Type="audio/mpeg" ProgID="LitViewHTML" />

     </MIMEAssociationList>

    <URLAssociationList>

      <URLAssociation Scheme="http" ProgID="LitViewHTML.URL.http" />

     </URLAssociationList>

     </Capabilities>

  </CapabilityGroup>

   </ApplicationCapabilities>

  </Extension>

</Extensions>

</ApplicationCapabilities>

Supported extension subsystems:

Machine Wide Virtual Registry extension subsystem sets a registry key in the virtual registry within HKEY_Local_Machine.


<Registry>

<Include>

  <Key Path="\REGISTRY\\Machine\Software\ABC">

    <Value Type="REG_SZ" Name="Bar" Data="Baz" />

   </Key>

  <Key Path="\REGISTRY\Machine\Software\EmptyKey" />

 </Include>

<Delete>

</Registry>

Machine Wide Virtual Kernel Objects


<Objects>

<NotIsolate>

   <Object Name="testObject" />

 </NotIsolate>

</Objects>

ProductSourceURLOptOut

Use ProductSourceURLOptOut to indicate that the URL for the package can be modified globally through PackageSourceRoot (to support branch office scenarios). Changes take effect on the next launch.


<MachineConfiguration>

  ... 

  <ProductSourceURLOptOut Enabled="true" />

  ...

</MachineConfiguration>

MachineScripts

The package can be configured to execute scripts at time of deployment, publishing or removal. To see a sample script, refer to the deployment configuration file generated by the sequencer.

The Scripts section below provides more information on the various triggers that can be used.

TerminateChildProcess

An application executable can be specified, whose child processes get terminated when the application exe process terminates.


<MachineConfiguration>

  ...   

  <TerminateChildProcesses>

    <Application Path="[{PackageRoot}]\Contoso\ContosoApp.EXE" />

    <Application Path="[{PackageRoot}]\LitView\LitViewBrowser.exe" />

    <Application Path="[{ProgramFilesX86}]\Microsoft Contoso\Contoso\contosomail.EXE" />

  </TerminateChildProcesses>

  ...

</MachineConfiguration>

Scripts

The following table describes the various script events and the context under which they can be run.

Script Execution Time Can be specified in Deployment Configuration Can be specified in User Configuration Can run in the Virtual Environment of the package Can be run in the context of a specific application Runs in system/user context: (Deployment Configuration, User Configuration)
AddPackage X (SYSTEM, N/A)
PublishPackage X X (SYSTEM, User)
UnpublishPackage X X (SYSTEM, User)
RemovePackage X (SYSTEM, N/A)
StartProcess X X X X (User, User)
ExitProcess X X X (User, User)
StartVirtualEnvironment X X X (User, User)
TerminateVirtualEnvironment X X (User, User)

Using multiple scripts on a single event trigger

App-V 5.1 supports the use of multiple scripts on a single event trigger for App-V packages, including packages that you convert from App-V 4.6 to App-V 5.0 or later. To enable the use of multiple scripts, App-V 5.1 uses a script launcher application, named ScriptRunner.exe, which is installed as part of the App-V client installation.

How to use multiple scripts on a single event trigger

For each script that you want to run, pass that script as an argument to the ScriptRunner.exe application. The application then runs each script separately, along with the arguments that you specify for each script. Use only one script (ScriptRunner.exe) per trigger.

Note

We recommended that you run the multi-script line from a command prompt first to make sure that all arguments are built correctly before adding them to the deployment configuration file.

Example script and parameter descriptions

Using the following example file and table, modify the deployment or user configuration file to add the scripts that you want to run.

<MachineScripts>
 <AddPackage>
   <Path>ScriptRunner.exe</Path>
   <Arguments>
   -appvscript script1.exe arg1 arg2 –appvscriptrunnerparameters –wait –timeout=10
   -appvscript script2.vbs arg1 arg2
   -appvscript script3.bat arg1 arg2 –appvscriptrunnerparameters –wait –timeout=30 –rollbackonerror
   </Arguments>
   <Wait timeout=”40” RollbackOnError=”true”/>
 </AddPackage>
</MachineScripts>

Parameters in the example file include:

<AddPackage>

Name of the event trigger for which you are running a script, such as adding a package or publishing a package.

<Path>ScriptRunner.exe</Path>

The script launcher application that is installed as part of the App-V client installation.

Note

Although ScriptRunner.exe is installed as part of the App-V client, the location of the App-V client must be in %path% or ScriptRunner will not run. ScriptRunner.exe is typically located in the C:FilesApplication Virtualizationfolder.

<Arguments>

-appvscript - Token that represents the actual script that you want to run.

script1.exe – Name of the script that you want to run.

arg1 arg2 – Arguments for the script that you want to run.

-appvscriptrunnerparameters – Token that represents the execution options for script1.exe.

-wait – Token that informs ScriptRunner to wait for execution of script1.exe to complete before proceeding to the next script.

-timeout=x – Token that informs ScriptRunner to stop running the current script after x number of seconds. All other specified scripts still runs.

-rollbackonerror – Token that informs ScriptRunner to stop running all scripts that haven't yet run and to roll back an error to the App-V client.

<Wait timeout=”40” RollbackOnError=”true”/>

Waits for overall completion of ScriptRunner.exe.

Set the timeout value for the overall runner to be greater than or equal to the sum of the timeout values on the individual scripts.

If any individual script reported an error and rollbackonerror was set to true, then ScriptRunner would report the error to App-V client.

ScriptRunner runs any script whose file type is associated with an application installed on the computer. If the associated application is missing, or the script’s file type is not associated with any application on the computer, the script does not run.

Create a dynamic configuration file using an App-V 5.1 manifest file

You can create the dynamic configuration file using one of three methods: either manually, using the App-V 5.1 Management Console or sequencing a package, which generates two sample files. For more information about how to create the file using the App-V 5.1 Management Console see, How to create a custom configuration File by using the App-V 5.1 Management Console.

To create the file manually, the information above in previous sections can be combined into a single file. We recommend you use files generated by the sequencer.

For App-V issues, use the App-V TechNet Forum.