Overview
Upgrading a free app
This page takes a binary installation of a free app 1.7.28 (-iis- zip of the site, IIS, SQL Server) to 1.8.0 keeping data and customizations. It applies to the three free apps; where something changes from one app to another the table below says so. Whoever installed the sources (-src- zip) does not use this page.
| Free app | Name ($Name) | Package prefix |
|---|---|---|
| Electronic invoicing | FatturazioneElettronica | fe |
| CRM | CrmApp | crm |
| Fleet management | FlottaMezzi | flotta |
You need:
- the
<Name>-iis-v1.8.0-with-dbs.zipzip of your app from the Download page of the site; - a Windows user that administers the machine and can back up and restore the two databases (the user that installed SQL Server Express can);
- a super administrator of the application (for example
admin).
The application is stopped during the upgrade. Do not extract the new zip over the application folder and do not restore its db\*.bak: they are for a new installation and would replace your data.
What is in the upgrade folder
The 1.8.0 zip has an upgrade\ folder:
| File | What it is for |
|---|---|
Upgrade-Database.ps1 | backup, data database scripts and restore of the two databases. It works with Windows PowerShell 5.1, without sqlcmd or SSMS: it reads the connection strings from the appsettings.json of the application |
db-data\*.sql | the data database scripts from 1.7.28 to 1.8.0, in the order they must run. They can be run again |
<prefix>-1.7.28.wuicpkg | metadata package of 1.7.28 as published: the base of the comparison |
<prefix>-1.8.0.wuicpkg | metadata package of 1.8.0 |
removed-files.txt | the program files of 1.7.28 that 1.8.0 no longer has (removed at step 6) |
upgrade.json | list and order of the scripts, names of the packages |
What is replaced and what is kept
| What | How |
|---|---|
program (DLLs, wwwroot, web.config) | replaced by the files of the new zip; the files of 1.7.28 that 1.8.0 no longer has are removed. If you had changed web.config, redo the change afterwards |
appsettings.json | kept: connection strings and settings stay yours, except uploadFolder (step 2) |
Upload, Conservazione, logs, App_Data | kept |
Reports (.mrt reports) | kept by the file copy; the metadata apply updates them (step 6) |
| data DB | updated by the scripts of upgrade\db-data |
| metadata DB | updated by the lifecycle with the <prefix>-1.8.0.wuicpkg package, 3-way with the 1.7.28 base |
Metadata and reports are compared 3-way: the base (1.7.28 as published), the source (1.8.0) and the target (your installation). What you changed and the vendor did not stays yours; what the vendor changed and you did not takes the new version; what you both changed is a conflict that you decide. An .mrt report is compared as a whole file.
Before you start
Open Windows PowerShell as administrator, write the name of your app in $Name (table above) and set the paths of your installation (the ones below are those of INSTALL.md). All the blocks of the page use these variables: run them in the same window.
$Name = 'FatturazioneElettronica'
$App = "C:\inetpub\wwwroot\$Name"
$Site = $Name
$Pool = "${Name}Pool"
$Zip = "$env:USERPROFILE\Downloads\$Name-iis-v1.8.0-with-dbs.zip"
$New = "C:\$Name-1.8.0"
$Copy = "C:\$Name-1.7.28-copia"
1. Stop the application and make the backups
Stop site and pool, wait until the pool process has exited, extract the new zip in a separate folder, back up the two databases and copy the application folder:
& $appcmd stop site "/site.name:$Site"
& $appcmd stop apppool "/apppool.name:$Pool"
while (Get-CimInstance Win32_Process -Filter "Name='w3wp.exe'" | Where-Object { $_.CommandLine -match [regex]::Escape($Pool) }) { Start-Sleep -Seconds 2 }
Unblock-File -Path $Zip
Expand-Archive -Path $Zip -DestinationPath $New
powershell -ExecutionPolicy Bypass -File "$New\upgrade\Upgrade-Database.ps1" -Action Backup -AppDir $App
robocopy $App $Copy /MIR /NFL /NDL /NP-Action Backup writes <database>_before-1.8.0.bak in the backup folder of the SQL Server instance and prints the path of each file. Keep backups and copy until you have checked the upgraded application: they are needed to go back (chapter Going back to 1.7.28).
2. Replace the application files
robocopy $New $App /E /XF appsettings.json /XD "$New\upgrade" "$New\db" "$New\Reports" "$New\Upload" "$New\Conservazione" "$New\logs" "$New\App_Data" /NFL /NDL /NProbocopy ends with a code from 0 to 7 when the copy succeeded; from 8 up there is an error.
Then the folder of the uploaded files. In the appsettings.json of 1.7.28 uploadFolder is C:\\src\\Wuic\\<Name>\\Upload, a folder of the vendor's machine: the uploaded files (for example the logo in the user tab) end up in C:\src\Wuic\<Name>\Upload, which the application creates. This block copies those files into the Upload folder of the application and empties the value, so the files uploaded from now on go to <application folder>\Upload.
$Old = "C:\src\Wuic\$Name\Upload"
if (Test-Path $Old) { robocopy $Old "$App\Upload" /E /NFL /NDL /NP }
$cfg = "$App\appsettings.json"
[IO.File]::WriteAllText($cfg, [IO.File]::ReadAllText($cfg).Replace("C:\\src\\Wuic\\$Name\\Upload", ''))The C:\src\Wuic\<Name>\Upload folder stays: 1.7.28 uses it again if you go back.
3. Update the data database
powershell -ExecutionPolicy Bypass -File "$New\upgrade\Upgrade-Database.ps1" -Action Scripts -AppDir $AppThe script runs the scripts of upgrade\db-data in the order of upgrade.json and stops at the first error, saying which script and which batch failed. The scripts can be run again: once the cause is fixed, run the same command again.
4. Restart the application
& $appcmd start apppool "/apppool.name:$Pool"
& $appcmd start site "/site.name:$Site"At the first start the 1.8 framework updates the schema of the metadata database by itself. Open the application in the browser and log in with the super administrator: the metadata are still those of 1.7.28 until you do steps 5 and 6.
5. Adopt the base (only the first time, from 1.7.28)
1.7.28 did not register its own version in the metadata database: you register it, without changing anything.
1. Open Administration → App lifecycle, Packages tab.
2. Upload package and choose upgrade\<prefix>-1.7.28.wuicpkg of the extracted folder (C:\<Name>-1.8.0). If the browser is on another computer, copy the two .wuicpkg to that computer first.
3. Compute plan, with Remove items missing from the package not checked.
4. If the plan shows conflicts (they are your customizations): Keep everything in the target.
5. Apply.
The plan keeps your installation as it is and registers the <prefix>-1.7.28 release, which from now on is the base of the comparison.
6. Apply the new version
1. Still in the Packages tab: Upload package and choose upgrade\<prefix>-1.8.0.wuicpkg.
2. Compute plan, with Remove items missing from the package not checked. Above the list of the conflicts, Base release must be <prefix>-1.7.28: without a base every difference would be a conflict.
3. For each item in conflict, Resolve and choose: All from the target keeps your version, All from the source takes the 1.8.0 one, Per-property choice decides property by property. Then Apply the choices and recompute the plan.
4. When there are no conflicts left, Apply.
Then remove the files of 1.7.28 that 1.8.0 no longer has (old libraries and client files that the application could still load or serve). Only the files listed in upgrade\removed-files.txt are removed: your files in the application folder stay. It is done here and not at step 2 because adopting the base (step 5) would put them back.
Get-Content "$New\upgrade\removed-files.txt" | Where-Object { $_ } | ForEach-Object { $f = Join-Path $App $_; if (Test-Path -LiteralPath $f) { Remove-Item -LiteralPath $f -Force } }Example with FatturazioneElettronica: if you had changed the labels of the dictionary of the stato_sdi column of fatture_inviate, which 1.8.0 changes too, the conflict is on that property only: with Per-property choice and Target you keep your labels and take the rest of the new route. A report you had changed and the vendor did not touch is not among the conflicts and stays yours; one changed by both is a conflict on the whole file.
7. Check
- The lists and the forms of the application open (for example, in FatturazioneElettronica, Fatture inviate and an invoice).
- Your customizations are still there.
- Compute plan again with
<prefix>-1.8.0.wuicpkg: there is nothing left to apply.
When you are satisfied you can delete the extracted folder, the copy and the backups.
If something goes wrong
- A data database script stops: the message says script and batch. Once the cause is fixed, run step 3 again; or go back to 1.7.28.
- The metadata apply answers with an error: read the result in the Packages tab; the page Metadata lifecycle explains the results of the apply.
- Undo only the metadata: in the Packages tab, on the row of the promotion with status
applied · <prefix>-1.8.0, Roll back brings the metadata back to before step 6. Program and data database stay at 1.8.0.
Going back to 1.7.28
Program, data database and metadata database go back to how they were at step 1: everything entered or changed afterwards (for example invoices and SDI outcomes in FatturazioneElettronica) is lost.
& $appcmd stop site "/site.name:$Site"
& $appcmd stop apppool "/apppool.name:$Pool"
while (Get-CimInstance Win32_Process -Filter "Name='w3wp.exe'" | Where-Object { $_.CommandLine -match [regex]::Escape($Pool) }) { Start-Sleep -Seconds 2 }
robocopy $Copy $App /MIR /NFL /NDL /NP
powershell -ExecutionPolicy Bypass -File "$New\upgrade\Upgrade-Database.ps1" -Action Restore -AppDir $App
& $appcmd start apppool "/apppool.name:$Pool"
& $appcmd start site "/site.name:$Site"-Action Restore closes the open connections and restores the two databases from the files of -Action Backup.