While upgrading existing UiPath projects to the new framework, sometimes they don’t compile properly or won’t run. It can be tricky to troubleshoot as there are many factors at play so I put this soft guide together to suggest some ways to fix it. It’s certainly helped us get through some challenging projects and it may help someone else so I’m sharing it beyond my own workgroup.
Troubleshooting Issues while Migrating UiPath Projects to Windows Framework
UiPath is vigorously pushing to end-of-life their old projects (now called Legacy) in favor of their newer Windows framework. The developer tool does offer an easy path to converting projects, but what do you do when that automated tool does not work? That’s what this post is all about.
Under the hood, your UiPath robotic solutions are built on a Microsoft .NET platform, and they have a reliance on many programming libraries. These libraries are not always 100% compatible with one another, and during the conversion process you may run into a situation where a solution worked under the Legacy framework, but during the upgrade to Windows framework these incompatibility issues become visible and render the upgrade a failure.
This can be tedious to troubleshoot, but here we are offering some suggestions for troubleshooting this process and (hopefully) ensuring your project successfully converts from Legacy to Windows without starting from scratch.
Why is it necessary to update?
UiPath has made it clear that this new Windows framework is the future of the product, and older versions will eventually stop working. Already they’re warning that new projects will soon be unable to be created in the Legacy framework.
Upgrading your existing workflows to the new framework will prevent you from being unable to get support, and ensure your RPA solutions continue to work for some time.
Remove Unused
There is a handy tool in UiPath for getting rid of assets that are unused. It can be dangerous to automatically pull these out of your project when you’re already concerned about the project’s reliability, so we will say this now and then repeat it many times: Always backup your project before attempting these steps!
(To backup your project, you can find the project folder and then navigate up one level in the directory and just copy/paste the project folder somewhere safe. Remember to copy not move the project.)
The “Remove Unused” tool is at the top of the Developer menu bar and gives you several options. We recommend starting with WORKFLOWS. Remove the unused, then test the project.
Next, remove unused ARGUMENTS. Test the project.
Next, remove unused DEPENDENCIES. Test the project.
If you’ve cleaned up the unused components and the project is still working, then we’re ready for the next step. This is a great time to backup your project again!
Manage Packages
This seems to be where the really serious problems can arise in the update process. These libraries of packages are critical to giving your project the functionality they need, but the versions can sometimes be incompatible and doing the Windows framework update definitely brings out hidden problems.
You should have already backed up your project from the first part of this process, but if you didn’t - please backup your project before doing these steps!
Click on the “Manage Package” icon on the Developer toolbar. This brings up the Manage Package dialog. Here you will see a list of all the packages that are powering your project. DO NOT UPGRADE THEM ALL AT ONCE!
We want to discreetly update our packages one at a time, to make sure that we can identify when an updated package is problematic. It is a very, very good idea to take a screenshot of your versions before messing about with this process.
Pick one of the packages and click on the little blue “up” arrow. Now, click the package name and a new menu appears to the right of the package list. Here you can use a drop-down menu and select specifically which version of the package you want to switch to.
This menu will allow you to Upgrade or Downgrade the version. Usually this means you won’t be stuck with a broken project, but can revert back to the version you had before. However, you will need to remember what that was, so hopefully you took that screenshot we told you to take?
Process:
- Select a package to update
- Click the blue up-arrow
- Click on the package name in the list to show you more details
- Review the package settings and make sure you’re going to the version you want
- Click SAVE button
Unless you have special knowledge of why a particular package version is needed, a good rule of thumb is pick the latest version and then test it. If that doesn’t work, you can downgrade the package by versions until you find one that works.
After each upgrade you need to test your project. If you have many packages to update, it is advisable to backup your project throughout this process so that you don’t have to start from scratch if one of the packages becomes a source of problems.
Update the Project to Windows Framework
Finally, once you’ve cleared the dependencies and gotten the libraries to the latest versions that are all mutually compatible (the project still works) it’s time to try updating your project to the new framework.
Open your project - the version that’s been the recipient of all the attention above. On the Project tree (left of your development palette) right-click on the project name. The option “Convert to Windows” should be in the list for you to click.
The “Convert to Windows” dialog will appear. Make sure you keep the checkbox to “create a new project” selected. YOU WANT TO CREATE THIS COPY IN A NEW FOLDER. Please don’t try updating back into your working project because if things go wrong you’re going to be unable to put things back like they were, except for restoring from one of the helpful backups we told you to make along the way.
If the project converts without errors, you should test it but you’re probably good to go.
If the project converts but throws errors, you will need to examine the logs to see what went wrong. Figuring out the issues for your particular project is beyond the bailiwick of this humble instructional article, but you can definitely put out your issue to the UiPath forums where other coders may have suggestions. And if that still doesn’t work, we can always open a ticket with UiPath but we’ve had good success following the above guidance and hope you will too.