Scripting and Embedded Scripting for AppV 5.0 (Dynamic Deployment and User Configuration Scripting)

Article
12/10/2012

written by Josh Davis, SDET 2

One of my early surprises at Microsoft was when I was working on a test machine doing some typical investigations. In Microsoft, it is fairly common to have a test machine provisioning solution that is custom tailored to your team’s needs and configures things in such a way that you automatically get good logging, all the diagnostic switches are flipped on, the post-mortem debugger is enabled and whatever other diagnostic knobs are otherwise enabled. So I was digging through the machine registry and noticed a registry path that seemed a little odd. The path in question was something like HKLM\SOFTWARE\Wow6432Node\Software\Microsoft\TestNode. Nothing out of the ordinary on the surface there, right? The problem was that I was on an x86 (32bit) machine. Without going into a rabbit hole of 64 bit vs. 32 bit OS Windows architecture, Windows added the Wow6432Node to handle the nuances between 32 and 64 bit registry code. In other words, there is no reason to have a Wow6432Node on a 32 bit OS. In my case, the TestNode was created by the provisioning structure and the script author decided it was easier to just blast potentially unnecessary registry data to the native node and the WOW node rather than doing the “correct” detection and only laying down what was necessary. Rather than trying to determine the architecture of the OS, the architecture of the process and crafting a way to walk around the potential registry redirection done by the OS, the author went for the “big hammer” approach.

What’s my point? Well, we all have to make really hard decisions in our jobs and determining which registry to write usually isn’t one of them. So even though “we’re Microsoft” and this process wouldn’t fly for a shipping product, when we’re talking about spinning up test environments, it’s more important that we spend the time on testing the product rather than creating the perfect test environment (which could be a whole blog in its own right).

In effect, the tools (editing the registry in a particular way) weren’t available to us in the fashion that we wanted and so we made a little bit of a mess in the process. You can’t blame us right? We made the impact small, but there was a cost tradeoff. Many scripts are written with that exact goal in mind. I need to execute some “one off” task but I want to keep the scope as small as possible. In the context of AppV 5.0, we’ve built a scripting feature that hopefully enables you do to just that.

Targeted Scripting

AppV 5.0 introduces a new management process for packages called Dynamic Configuration. Dynamic Configuration allows you to specify a policy for a package at either the machine level or at the user level. While there is much more in Dynamic Configuration than just scripts, we will only be talking about scripts in this post. So with the dynamic configuration documents, you can control whether you want to run a script at a machine level (global—typically used in an RDS scenario), or at a user level (1 user per machine or when you want different scripts run depending on the user) we provide you that flexibility. Also, we allow you to run scripts at various execution times of the package lifecycle. Below is a table that helps describe the various script events and when and how they can execute.

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 only once per package event*	Runs in user context: (Deployment Config, User Config)
AddPackage	X				X	(SYSTEM, N/A)
PublishPackage	X	X				(SYSTEM, User)
UnpublishPackage	X	X				(SYSTEM, User)
RemovePackage	X				X	(SYSTEM, N/A)
StartProcess		X	X	X		(N/A, User)
ExitProcess		X		X		(N/A, User)
StartVirtualEnvironment		X	X			(N/A, User)
TerminateVirtualEnvironment		X				(N/A, User)

*A script only runs once in certain contexts because it often doesn’t make sense to rerun it. E.g. if at AddPackage you add a script that installs a driver, but you modify the package and update the package path (via Set-AppVClientPackage, for example) you wouldn’t want to re-install the driver again so we don’t run the script. There is a potential issue (especially during script development) when you do want to rerun a script or update the deployment config (e.g. update the script argument list). In order to accomplish this, you will need to clean the package state so the event retriggers afresh (e.g. If you want to update the AddPackage script, you need to remove the package then add it again).

What this means is that you can write a script and it will be run at any of these events specified. For example, suppose you have a package that has a driver that needs to be extracted and deployed in order for the package to function correctly. Since AppV does not virtualize drivers, the only way to do this would be to install the driver natively. Rather than push this out to all users or try to write your script to call into AD to determine who needs it, etc., you can simply add this script to a Dynamic Configuration file (either Deployment or User) as a “PublishPackage” script (or “AddPackage” in the deployment configuration file) so that it’s available to the user by the time the package is. Here’s an example:

<Path>powershell.exe </Path>

<Arguments>-file installDriver.ps1</Arguments>

</PublishPackage>

Enabling Scripting

Now that you’ve decided you want to actually use a script in your environment, you’ll first need to enable it for the machines you are targeting. This can be done by setting the client configuration setting “EnablePackageScripts”. This can be done at install time, through group policy or through powershell. Here is how you would do it in powershell:

PS > Set-AppvClientConfiguration -EnablePackageScripts $true

Microsoft believes in a secure system and frankly, if you don’t want any scripts executed in your environment, we want to enable you do that. And since we believe that a lot of scripting scenarios are reduced by our investments we’ve made in the 5.0 release, we opted for defaulting that scripts be disabled so that you the admin can make a conscious decision that scripting is still a necessary part of AppV in your environment.

User Context Execution

It should be fairly obvious (if one stops to think about it) that machine scripts will execute in a machine context (specifically “NT Authority\System” context) and that user scripts will execute in the user context. Obvious if one stops to think about it. However, all the implications of that may not be so obvious. Here are some examples of some “gotchas” that might show up in your scripts if you’re not careful and how you can resolve them. Pay attention to user context when considering your scripts.

1. Powershell scripts won’t execute

As a powershell script author, you’re no doubt familiar with the Get- and corresponding Set-ScriptExecutionPolicy cmdlets for enabling the execution of scripts. These settings are probably configured via a global group policy for the corporate domain and are “secure by default” settings that typically show up when you’re authoring scripts on test machines. In other words, the setting is probably something you “set and forget” and then remember only when you’re trying to spin up a new machine, write a new script, etc. Whatever the case, take the below script example. While you might have taken care to remove the security policy for your user scope by calling something like “Set-ScriptExecutionPolicy –ExecutionPolicy RemoteSigned”, you might not have noticed that the default “Scope” for this cmdlet is the current user scope. Meaning, it won’t affect the SYSTEM context at all. In the example below, you can see that we pass the “-ExecutionPolicy ByPass” value in the arguments to that script. You can also change the execution policy for a broader scope as well. Note, you should make sure your scripts adhere to your corporate security policies; this is just an example. As another aside, you can pass additional arguments to the script as in the below example (arg1, arg2).

<Path>powershell.exe </Path>

<Arguments>-ExecutionPolicy ByPass -File installDriver.ps1 arg1 arg2</Arguments>

</AddPackage >

2. Scripts are unable to access certain resources

You write a script that parses a file for some settings and then configures the user’s machine appropriately. This can go wrong because the user might not have access to a particular resource (SYSTEM32) or maybe the machine SYSTEM account doesn’t have access to your network user share. Pay attention to the kind of script event that you are executing and consider whether there are permissions issues that might arise in your production environment that wouldn’t in your test environment.

Writing a Script

Referencing script collateral

The first element you need to know about in the script object is the “Path” element. The path element represents the executable (yes, the binary you specify must be a .exe executable) that will be executed when the script is run. The path can be to a local or UNC path or can be a file embedded in the package (this is why sometimes call the feature “Embedded Scripting”). To access local system files or UNC files, you must use a full path. To access files inside of the package you can specify a relative path or a tokenized path. The working directory of the script is the root of the package (e.g. C:\ProgramData\App-V\A2D337CF-BAFD-4A51-A385-466B9E6053A7\B83CE87D-558A-4C20-BF23-B663BF19D922) so you can specify a script file with a relative path by doing something like the below:

<Path>powershell.exe </Path>

<Arguments> .\Scripts\InstallDriver.ps1 </Arguments>

</PublishPackage>

Or, since the Script node and the Package root are siblings, you can use a relative path from the [{AppVPackageRoot}] token:

<Path>powershell.exe </Path>

<Arguments >[{AppVPackageRoot}]\..\Scripts\InstallDriver.ps1 </Arguments>

</PublishPackage>

Introducing “blocking” logic

The “Wait” element can be used to introduce synchronization logic if the script is critical (i.e. is necessary in order for the package to work correctly). For example, in our driver scenario above, the application may not function correctly if the driver is not properly installed. “RollbackOnError” should be set to “true” in this case since the package is nonfunctional without it. Since you are introducing additional logic that may lock the publishing process, we allow a timeout in seconds to indicate how long the event should wait for the process to exit. In this case, we set it to two minutes for the installer to run. If it exits sooner, the event (a publish in this case) will complete. If it does not exit in time, we will fail.

You can imagine a scenario where the script is non-critical. E.g. you want to do some cleanup of some user data files if they are present, but it’s not critical to the package. In this case, you can set RollbackOnError to false or remove the <Wait> element altogether. Keep in mind, if you remove the <Wait> element, it will be executed asynchronously, meaning that we won’t wait at all for it to complete successfully or even to complete at all. So even if you don’t care whether it succeeds or not, you might want to keep the <Wait> element present anyway, then again you might not. An example of where you might want the <Wait> with <RollbackOnError>False</RollbackOnError> is where the event runs an installer on AddPackage, you don’t care whether it completes successfully, but you do care that it completes because subsequent steps or scripts will also attempt to do an install and if an install is in progress, they will fail. Specifying <Wait> allows you to be sure that the process exited.

The Timeout default is ‘0’ and does not need to be specified. A timeout of ‘0’ means “wait indefinitely” for the process to exit.

Runtime Flags

In addition to the blocking logic, there are flags that can be specified for Runtime Script events. Runtime script events are what I call the virtual application time scripting events like Process start or VirtualEnvironment shutdown. This can get a little tricky so let me spell of the flags out in detail.

RunInVirtualEnvironment – a Boolean (value can be ‘True’ or ‘False’) attribute which if specified, will dictate whether or not the script will run in the VE. If the attribute is not specified, by default the script will not run in the VE (the ‘VE’ represent the isolated package virtual environment including runtime (process and service objects) and state (filesystem and registry). Running a script in the VE will allow the script to run “in the bubble” of the virtual package. Keep in mind, a virtual environment is package specific (or package group if there is a connection group) and not app specific. A change to one app in the package will affect all apps in the package. Script events that can specify this attribute are ‘StartProcess’ and ‘StartVirtualEnvironment’

ApplicationId – Nonnullable. This is the token which represents the app associated with a process. In other words, when you click an app, say ‘Microsoft Word 2013’ it corresponds to a shortcut (on the desktop for example), this shortcut points to a file on disk called WinWord.exe and that object is represented with in the manifest and the default dynamic config files generated by the Sequencer as an ApplicationId. We use the application Id to track a number of things about the application and to make the application virtualization experience appear more native. The point for scripting though is that we use these tokens to uniquely represent an app so that when the end-user clicks a desktop shortcut, we know what app and what script to run. Only ‘StartProcess’ and ‘ExitProcess’ can specify this attribute and it is required for those scripts.

Embedding a script in the package

We previously referenced the “Scripts” directory under the package root. What is the significance of this directory? Well, firstly, it gives the sequencing engineer a common place to add scripts and script collateral to the package. This is so the package can be completely self-contained without referencing shares or local system resources (other than Powershell or something similar to run the script). Of course, if you want to put scripts on a share, that is fine, but if you don’t, AppV 5.0 enables this scenario for the first time. In the Sequencer “Package Files” tab, you will find the “Scripts” directory entry pre-created for you. By default it is empty, but if you want to embed a script file in the package, you can add a file here (see picture below)

Of course, this is not limited to scripts and executables but you can also add script collateral like .reg or .xml files, or any other collateral you might need. The special thing about collateral in this directory is that it is automatically streamed as part of the publishing of the package. I repeat, it is automatically streamed as part of the publishing of the package. So if you need the files to be there on user publish, they will be as part of the “Publishing Feature Block”. But if you are super concerned about keeping your publishings lightweight then you won’t want to do this because it could considerably slow down your publishing times depending on your users’ bandwidth and the size of the script payload.

How do I modify the Dynamic Configuration XML?

The easiest way to do this is to take the dynamic config files as generated by the Sequencer and modify them from there. User scripts can be specified in the ‘Dynamic User Configuration’ xml files (<PackageName>_UserConfig.xml, by default), while machine scripts can be specified in the ‘Dynamic Deployment Configuration’ xml files (<PackageName>_DeploymentConfig.xml, by default). As noted by the above table, some script events only make sense in a machine (‘deployment config’ essentially means ‘machine config’) like “AddPackage” since a user cannot add a package and—even if a user could add a package—there wouldn’t be a user to associate the ‘AddPackage’ event with since the package has not yet been published to any users yet.

So user scripts go with user configuration and machine scripts go with machine—er deployment—configuration.

Gotchas

There are some things that make sense when you are really thinking about it, but chances are (if you’re like me) you’re not always really thinking. Below are some bullet point examples:

1) Some scripts won’t rerun if you’re repeating the same event. Take for example a package publish. In this case, we have an event that could conceivably be done many times (for example on every login) but the script event is intended generally going to be for a user specific one-time configuration (running an installer in a user context for example) which cannot be done at time. The problem with this is that if we didn’t prevent the script from running again and again, then this installer would get run repeatedly and—if this installer wasn’t written to handle repeated installs—could cause some serious trouble. So we play it safe and think of add/publish/unpublish/remove scripts as one-time scripts. That is, one time per unique package ID and package version ID. If the package is upgrade (new Version ID) then we will re-run that script because for all we know it is a dramatically different package. The trick here is that if you publish a package and then decide you want to configure a runtime script _after_ the package has already been published then the script will not run. You will need to either upgrade the package or else unpublish and republish the package for the new script to take effect.

2) Powershell may require additional arguments in order to invoke the script. An example of this might be setting the execution policy explicitly for the script. Imagine that you have set the Powershell execution policy globally for your environment to be ‘Restricted’ which is the Powershell default. This would mean that no scripts can be run on the machine at all—clearly a problem if you want to run a powershell script to configure a package. Not to fear, Powershell.exe exposes overrides to combat this very problem. You can pass in “-ExecutionPolicy Bypass -File <path to script>” and override the execution policy assuming that you are running in an admin context. This would allow you to run scripts for a machine event (or a user event if the user is an admin) without changing the global execution policy for that machine or user. It will only persist across that single script session.

3) User scripts cannot be placed in the UserConfiguration section of the deployment policy. User scripts run in a user context and will only be invoked for user Publish and Unpublish as well as the corresponding runtime events (Start/Stop Process/VirtualEnvironment). If you do this, the package add will fail as this will invalidate the deployment config schema.

That’s it for this post. If I get enough demand, maybe I’ll post a bunch of different real-world examples of scripts in a future post.

Thanks for reading!

Comments

Anonymous
January 01, 2003
As far as I know, you can't get the package/version id from any variable. However, you could use something like powershell to parse the guid from the path, e.g.$path = [System.IO.Path]::GetDirectoryName( $pwd ); $dirs. = $path.Split("/"); $packageID = $dirs[$dirs.Length - 2]; $versionID = $dirs[$dirs.Length - 1]
Anonymous
January 01, 2003
The comment has been removed
Anonymous
January 01, 2003
How do publish office 2013 globally from App-V management server...
Anonymous
January 01, 2003
Where do I paste this script in DeploymentConfig.xml?

In App-V 4.6 this would go between the dependency tags. But where should I include it in App-V 5.0 - where within DynamicConfig.xml?

Is it here under User Scripts? What should I eliminate from here to paste my script?

-

Could you please let me know if some one got a solution for the above issue.
Anonymous
February 12, 2013
same problem here... and no resolution to find at google
Anonymous
February 14, 2013
Hi, I virtualised FireFox 18.0.2. on Appv 5. Would like to customize it for our organisation. I need to add mozilla.cfg to where firefox.exe resides. I need to add all.js to prefs directory under Firefox Could you please let me know the exact syntax & where they should be placed in the Dynamic Configuration file? <AddPackage> <Path>powershell.exe </Path> <Arguments>Create C:Firefox18.0.2mozilla.cfg </Arguments> .// . .//Disable updates .lockPref("app.update.enabled", false); .lockPref("app.update.auto", false); .lockPref("app.update.mode", 0); .lockPref("extensions.update.enabled", false); .lockPref("browser.serach.update", false); <Arguments>Add these lines to the end of C:Firefox18.0.2prefsall.js </Arguments> .//Config file is plain text .pref('general.config.obscure_value', 0); .//This is the config file .pref("general.config.filename", "mozilla.cfg");
Anonymous
March 29, 2013
Where do I paste this script in DeploymentConfig.xml? <SCRIPT TIMING=”PRE” EVENT=”LAUNCH” WAIT=”TRUE” PROTECT=”TRUE”> <SCRIPTBODY> Q:CS6-FlashCS6-Flash-SerialAdobeSerialization.exe adobe_prtk ––tool=VolumeSerialize ––provfile=Q:CS6-FlashCS6-Flash-Serialprov.xml </SCRIPTBODY> </SCRIPT> In App-V 4.6 this would go between the dependency tags. But where should I include it in App-V 5.0 - where within DynamicConfig.xml? Is it here under User Scripts? What should I eliminate from here to paste my script?

- Anonymous
  June 22, 2016
  Although this article is really good it fails to explain a few things that are key to getting your use scripts running.You MUST point the path variable to an .exe, meaning that if you have a script that you used to run (such as a .bar or .cmd) you will need to point the path variable to cmd.exe and then point the arguments to the file you wish to run. This also means that if you have raw code in your .osd files you will need to move this code into a file that can be ran as part of an argument.I spent ages trying to edit the userconfig file in the root of my sequenced package, getting rather frustrated that it wasn't working. The actual config file that you need to edit can be downloaded from your App V server website. Nagivate to package, edit the AD groups and set the config to custom. A new link will appear which will take you to another config page, click on advanced and then click download config file.This config file is the one you need add your userscript code to. Then click on the upload config option when you are done, select the config file you where just editing and you are done.

Anonymous
October 18, 2013
MachineConfig Vs UserConfig when publishing only to User Groups We added a script to install a drivers with system rights in a deployment config xml We set this xml as "default" by editing "Default Configuration" on package and importing Deployment.xml into this "default configuration" Then we published the package to a group of user without any "custom configuation" just the "Default one" Does the script run (because of "default" machine) even I published the package to "User only" If I want to run a "machine" script in a (default) "deployment Config" did I need to publish to a Machine ?
Anonymous
October 24, 2013
Is there a way for the script to pass the version id / package id of the package to the arguments?
Anonymous
November 15, 2013
Hi, Need to know how to use the XML files, If I install the App-v 5.0 packages only through MSI. Thanks
Anonymous
January 16, 2014
In the article you mention that the working directory for a script is het package root directory. We did experience though that that did not work. Looking with Process Monitor we see the working directory for a StartVirtualEnvironment script as follows: C:ProgramDataApp-V2EA8785A-3D3E-498A-94FA-D43627C118F7�64850F5-6E45-4AE5-BEE6-9243997F906EScripts.So it is actually the Scripts directory itself. Is there an official documentation on this? Just to be sure we will for now work with the 'sibling path' approach to specify the full path..
Anonymous
January 30, 2014
Hello everyone, John Behneman here again. Recently I had case where a customer wanted to modify policy
Anonymous
February 16, 2014
Yes, there is a learning curve with the new release of App-V. This is why it is extremely important that
Anonymous
February 16, 2015
Where do I paste this script in DeploymentConfig.xml?

In App-V 4.6 this would go between the dependency tags. But where should I include it in App-V 5.0 - where within DynamicConfig.xml?

Is it here under User Scripts? What should I eliminate from here to paste my script?

-

Have some one got a solution for this....
Anonymous
February 16, 2015
Where do I paste this script in DeploymentConfig.xml?

In App-V 4.6 this would go between the dependency tags. But where should I include it in App-V 5.0 - where within DynamicConfig.xml?

Is it here under User Scripts? What should I eliminate from here to paste my script?

-

Have some one got a solution for this....
Anonymous
February 16, 2015
Where do I paste this script in DeploymentConfig.xml?

In App-V 4.6 this would go between the dependency tags. But where should I include it in App-V 5.0 - where within DynamicConfig.xml?

Is it here under User Scripts? What should I eliminate from here to paste my script?

-

Could you please let me know if some one got the solution for the above issue issue.
Anonymous
March 04, 2015
To an AD machine_group and set client -
Import-Module AppvClient
Get-AppvPublishingServer | Set-AppvPublishingServer –GlobalRefreshEnabled 1 –GlobalRefreshOnLogon 0 -UserRefreshEnabled 0 -UserRefreshOnLogon 0
Get-AppvPublishingServer | Sync-AppvPublishingServer -Global
Anonymous
March 04, 2015
Can you please give us a feedback on the table mentionned on your partner site? (http://www.tmurgent.com/TMBlog/?p=1154)
We thought that an "publish/unpublish" script placed in DeploymentConfig.xml / User Configuration should run as SYSTEM account. In practice, it's USER. This table was very clear (comparing to your table, sorry ;-)), but probably not true. Can you please clarify?
It's annoying for us as we are publishing packages only to users, not machine. Our goal is to clean the disk (remove package) after unpublishing. This requires admin rights.
Thks in advance
Anonymous
March 19, 2015
The above article is required pre-reading for understanding, then for Tim M's further discussion, can go here:
http://www.tmurgent.com/TMBlog/?p=1154
Anonymous
June 30, 2015
~ John Behneman | Senior Support Escalation Engineer Hello everyone, John Behneman here again. I’d like
Anonymous
June 30, 2015
~ John Behneman | Senior Support Escalation Engineer Hello everyone, John Behneman here again. I’d like
Anonymous
July 22, 2015
Bal3k when you want to publish a package globally you need to import the package and select under the options of the package import xml file and import the deployment configuration.xml file which was made during saving the package.
Anonymous
July 22, 2015
Hello, while we are on this subject. I like to ask this question for anyone that can help.

I wanted to see if I could include a test.ps1 scripts inside the "Scripts" folder so it can be loaded in the Feature Bit 0 and will run when it's published. All the test.ps1 script is doing is creating a text file in C:Temp.

I uncommented the user script section so it will run. This is what I have.

Powershell.exe
-ExecutionPolicy ByPass -File [{AppVPackageRoot}]..ScriptsTest.ps1

Does anyone know why this is not running? I'm using the {AppVPackageRoot} varible, do I need to also append the versionid to the path? Or should this work? When I publish the app, I like to see a log file created. Please know that I'm only creating a log file to see if the PowerShell scirpt is running.

Any advice woudl be greatly appreciated.
Anonymous
November 12, 2015
@TheInfamousOne

1. Have you enabled scripting?
2. Is there any event log traced?
3. User scripts will run only in domain joined machines. Have you tested in domain joined computer?
4. Also try changing the path from [{AppVPackageRoot}]..ScriptsTest.ps1 to .ScriptsTest.ps1

I would recommend you to post in Technet App-V forum to get prompt reply.
Anonymous
April 13, 2016
Please post some real-world examples when you can. Thanks
Anonymous
May 19, 2016
What if we want the script to add a marker file to sit on the C:\drive? I can see how I can script a copy of the file from the VFS to the physical drive during a publish, however how do we reverse that when we unpublish the package?Or for that matter how do we uninstall the driver as part of an unpublish?

Share via

Scripting and Embedded Scripting for AppV 5.0 (Dynamic Deployment and User Configuration Scripting)

Targeted Scripting

Enabling Scripting

User Context Execution

Writing a Script

Referencing script collateral

Introducing “blocking” logic

Runtime Flags

Embedding a script in the package

How do I modify the Dynamic Configuration XML?

Gotchas

Comments

Additional resources