Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 50 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,13 +115,14 @@ in the next section.

`UniGetUI.PackageEngine.Managers.MacPkg` (id `pkg`, macOS only) installs IT-published `.pkg` and
`.dmg` files through the Software Catalog; the administrator workflow is in `docs/PKG_FEEDS.md`.
Its format-agnostic parts live in the shared feed project described in the next section.

- Its sources are not added from the UI: each catalog of the machine-wide `SoftwareCatalog.json`
that has a `pkgFeed` declares one, named by the catalog's id and shown by its name
(`PkgCatalogFeeds`, `PkgFeedSource`), with `Sources.CanBeEdited` false. The catalog page
(`CatalogFeeds`, `InstallerFeedSource`), with `Sources.CanBeEdited` false. The catalog page
then lists every package of that feed in the catalog (`SoftwareCatalogViewModel.ExpandPkgFeedsAsync`).
- A feed is a `file:` folder whose `.pkg` files are read directly, or an `https:` folder read through
the `index.json` that `unigetui pkg-index <folder>` writes (`PkgIndexCommand`).
the `index.json` that `unigetui pkg-index <folder>` writes (`PkgIndexCommand`, an `IFeedIndexer`).
- Identity comes from the file itself: for a `.pkg`, `XarArchive` + `PkgMetadata` (the first
component of a Distribution, else `PackageInfo`, plus its outermost app); for a `.dmg`,
`DiskImage` mounts it read-only and reads the app at its root. Installed state comes from
Expand Down Expand Up @@ -151,6 +152,53 @@ in the next section.
- The Catalog Editor's **Package feed** dialog (`PkgFeedEditor`, `PkgFeedEditorViewModel`) edits
`pkgFeed`/`allowUnsignedPackages` and previews a feed through `PkgFeedInspector`.

## Installer feeds shared by macOS and Windows

`UniGetUI.PackageEngine.Managers.Generic.InstallerFeeds` holds what does not depend on the file
format: the catalog's feed declarations (`CatalogFeeds`), feed locations and index path checks
(`FeedLocation`), the cached folder/web listing with its last-known fallback (`FeedListing<TItem>`),
the `index.json` schema (`FeedIndex`), sources (`InstallerFeedSource`, `InstallerFeedSourceHelper`),
staging (`FeedStaging`) and the `pkg-index` command (`FeedIndexCommand` over an `IFeedIndexer`).

One `pkgFeed` and one `index.json` serve both platforms. macOS entries stay under `packages`, the
key older Macs read in full, and Windows entries go under `windowsPackages`, which they ignore, so a
Mac never lists an installer it cannot run, whatever its release. Each reader also refuses entries
whose file extension it does not own. `pkg-index` writes its own platform's list and keeps the other
one while its files still hash the same, so a mixed folder is indexed by running it once on each.

## Windows installer packages (.exe and .msi)

`UniGetUI.PackageEngine.Managers.WinInstaller` (id `installer`, Windows only) is the Windows
counterpart of `pkg`; the administrator workflow is in `docs/WINDOWS_INSTALLER_FEEDS.md`.

- Identity comes from the file: an `.msi` through msi.dll (`MsiDatabase`: Property table and the
summary Template), keyed by its `UpgradeCode`; an `.exe` through a managed, bounded PE reader
(`PeReader`: version resource, sections, appended data, largest icon) and `InstallerKinds.Detect`
(Inno Setup, NSIS, WiX Burn, InstallShield). A `<name>.json` beside the file
(`InstallerManifest`) fills in or overrides anything, and is required for an unknown installer's
silent switches. `pkg-index` bakes all of it into the entry's `windows` block.
- Installed state comes from Apps and Features (`ArpEntries`, both registry views of HKLM and
HKCU), matched by `InstalledMatcher`: the manifest's `uninstallKey`, else an MSI's related
products or a bundle's `BundleUpgradeCode`, else, for an `.exe` only, its cleaned display name
with an agreeing publisher. `InstallReceipts` remembers the registered version an install left,
so an installer whose `DisplayVersion` differs from its own version is not offered forever.
- Installs run in-process (`WinInstallerRunner`): stage a private copy held open against writes,
verify the index hash, the identity (re-read with the original manifest) and Authenticode
(`Authenticode`, WinVerifyTrust, waived only by `allowUnsignedPackages`), then run it silently,
an `.msi` through `runas` unless it is per-user, an `.exe` unelevated unless its manifest says
`"scope": "machine"` (Inno and Burn elevate themselves; ERROR_ELEVATION_REQUIRED retries
elevated); `ProhibitElevation` refuses. Uninstalls run the registered command made silent and,
for an `.exe`, wait for the entry to disappear, since NSIS uninstallers return at once. An entry
elevates only when it is per-machine, which for Windows Installer products comes from their
`AssignmentType`, not the hive: per-user MSI products are registered under HKLM too.
- Tests swap `ArpEntries.Source`, `InstalledMatcher.RelatedProducts`, `Authenticode.Verify` and
`WinInstallerRunner.RunProcess`; `WinInstallerTests` builds real `.msi` fixtures through msi.dll
and `.exe` fixtures from `cmd.exe` plus an appended NSIS or Inno header.
`WinInstallerEndToEndTests` installs, updates and uninstalls real per-user MSI and Inno Setup
packages (folder and web feeds, and through the operation classes) when
`UNIGETUI_INSTALLER_E2E=1`, and per-machine ones behind UAC when it is `elevated`; otherwise
they report as skipped.

## Version comparison across ecosystems

`CoreTools.VersionStringToStruct` treats `-`, `_`, `/` and `#` as plain numeric separators and
Expand Down
2 changes: 1 addition & 1 deletion docs/CLI.md
Original file line number Diff line number Diff line change
Expand Up @@ -357,7 +357,7 @@ These parameters are accepted by the app executables in addition to the automati
| `--delete-shortcuts <path> [<path>...]` | Deletes desktop or Start Menu shortcuts, then quits. | Used by UniGetUI to remove shortcuts the current user is not allowed to delete; refuses any path that is not a `.lnk` or `.url` under a desktop or Start Menu folder. |
| `<bundle-file>` | Loads a valid bundle file into the Package Bundles page. | Supported extensions include `.ubundle`, `.json`, `.yaml`, and `.xml`. |
| `pkg-helper install-daemon` / `remove-daemon` | Installs (or removes) the root service that lets standard users install catalog packages without an administrator password. | macOS, as root. `pkg-helper serve` is what the service runs. See [PKG_FEEDS.md](PKG_FEEDS.md). |
| `pkg-index <folder>` | Writes the `index.json` that publishes a folder of macOS `.pkg`, `.dmg` and `.zip` files as a web feed, then quits. | macOS and Linux builds only; `.dmg` files are read on macOS only. Exits 3 when a file in the folder could not be read. See [PKG_FEEDS.md](PKG_FEEDS.md). |
| `pkg-index <folder>` | Writes the `index.json` that publishes a folder of packages as a web feed, then quits: `.exe` and `.msi` files on Windows, `.pkg`, `.dmg` and `.zip` files elsewhere. Entries another platform wrote are kept while their files are unchanged. | `.dmg` files are read on macOS only. Exits 3 when a file in the folder could not be read. See [PKG_FEEDS.md](PKG_FEEDS.md) and [WINDOWS_INSTALLER_FEEDS.md](WINDOWS_INSTALLER_FEEDS.md). |

## Other environment variables

Expand Down
3 changes: 3 additions & 0 deletions docs/PKG_FEEDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ The software catalog can offer apps that no package manager carries: an administ
the vendor's `.pkg`, `.dmg` or `.zip` unchanged, and users install and update it from the
**Software Catalog** page.

Windows `.exe` and `.msi` installers are published the same way, from the same feed if you like:
see [WINDOWS_INSTALLER_FEEDS.md](WINDOWS_INSTALLER_FEEDS.md).

There is nothing to repackage and no detection rule to write. UniGetUI reads each file's
identifier, version and app from the file itself, then checks the Mac:

Expand Down
172 changes: 172 additions & 0 deletions docs/WINDOWS_INSTALLER_FEEDS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
# Publishing Windows apps (.exe and .msi)

The software catalog can offer apps that no package manager carries: an administrator publishes
the vendor's `.exe` or `.msi` unchanged, and users install, update and uninstall it from the
**Software Catalog** page. This is the Windows counterpart of the macOS feeds described in
[PKG_FEEDS.md](PKG_FEEDS.md), and one feed folder can serve both.

For most installers there is nothing to write. UniGetUI reads each file's identity, version and
silent switches from the file itself, then looks for the app in **Apps and Features** (the
`Uninstall` registry keys of the machine and of the user):

- **`.msi`:** identified by its `UpgradeCode` (or its `ProductCode` when it has none), at its
`ProductVersion`. Installed when Windows Installer lists a product of that upgrade code, or the
product itself. Installed with `msiexec /i <file> /qn /norestart`.
- **`.exe`:** identified by the product name in its version resource, at its product version.
Installed when an Apps and Features entry carries that name (a trailing version or architecture
is ignored) from the same publisher. UniGetUI recognizes these installer technologies and their
silent switches:

| Technology | Recognized by | Install | Uninstall |
|---|---|---|---|
| Inno Setup | its setup data or version comment | `/VERYSILENT /SUPPRESSMSGBOXES /NORESTART /SP-` | `/VERYSILENT /SUPPRESSMSGBOXES /NORESTART` |
| NSIS | the header of its appended data | `/S` | `/S` |
| WiX bundle (Burn) | its `.wixburn` section | `/quiet /norestart` | `/quiet /norestart` |

Any other `.exe` (InstallShield, Advanced Installer, a vendor's own bootstrapper) needs its
silent switches written in a manifest, below.

So an app that was deployed by Intune, Configuration Manager or by hand is recognized, and updates
are offered for it.

## Set up a feed once

A feed is a folder, a share or a web folder holding `.exe` and `.msi` files. In the Catalog Editor,
select a catalog and choose **Package feed**: enter the folder or web address, then **Check feed**
lists every package it publishes and every file it skips, with the reason. Or declare it as the
`pkgFeed` of a catalog in the machine-wide catalog file, `%ProgramData%\Devolutions\UniGetUI\SoftwareCatalog.json`:

```json
{
"version": 1,
"catalogs": [
{
"id": "windows-apps",
"name": "Windows apps",
"packages": [],
"pkgFeed": "\\\\fileserver\\software\\windows"
}
]
}
```

Every package in the feed appears in that catalog. `packages` may stay empty; any entry listed
there as well is shown alongside the feed's packages. Outside the catalog page the id is the
package's source, as in `Installer packages: windows-apps`.

A feed can be:

| Location | Example | What UniGetUI reads |
|---|---|---|
| A web folder (https) | `https://software.example.com/windows/` | `index.json` in that folder |
| A local folder or a share | `\\fileserver\software\windows` | the `.exe` and `.msi` files directly |

Subfolders up to three levels deep are read too. Files whose name contains `uninst` are skipped,
since they are uninstallers.

### Signatures

Before installing, UniGetUI checks the installer's Authenticode signature the way Windows checks a
download (`WinVerifyTrust`, with revocation checks). Vendors' installers are signed. An installer
that is unsigned, tampered with, or signed by a certificate this computer does not trust is not
installed.

To publish your own unsigned installers, add `"allowUnsignedPackages": true` to that catalog, and
keep its feed where only administrators can change it.

## When the file cannot say it: the manifest

A `.json` file with the installer's name (`Vendor.exe` → `Vendor.json`) fills in or overrides what
UniGetUI reads. Every field is optional:

```json
{
"id": "Vendor.Tool",
"name": "Vendor Tool",
"version": "5.1",
"installArguments": "-s -norestart",
"uninstallArguments": "-s",
"displayName": "Vendor Tool Pro",
"uninstallKey": "{6B1F...}_is1",
"upgradeCode": "{11111111-2222-3333-4444-555555555555}",
"publisher": "Vendor Inc.",
"architectures": ["x64"],
"scope": "user"
}
```

- `installArguments`: the switches that install without any window or restart. Required for an
installer UniGetUI does not recognize; for an `.msi` they replace `/qn /norestart`.
- `uninstallArguments`: the switches added to the uninstaller the app registers (its
`UninstallString`) to make it silent. Given, they are used even when the app registers a silent
command of its own. For an `.msi` they replace `/qn /norestart`.
- `uninstallKey`: the exact name of the key the installer writes under `...\CurrentVersion\Uninstall`.
The most reliable way to recognize an installed `.exe`; with it, names are not compared.
- `displayName`: the name the app shows in Apps and Features, when it differs from its product name.
- `upgradeCode`: for a WiX bundle, its upgrade code, which recognizes every version of it.
- `architectures`: `x86`, `x64` or `arm64`. An `.msi` says it itself; an `.exe` is usually a 32-bit
installer whatever it installs, so give it when the feed holds one build per architecture.
- `scope`: `user` or `machine`. An `.exe` starts without administrator rights and asks for them
itself when it needs them, as Inno Setup, WiX bundles and most installers do; give `machine` for
one that fails instead of asking, so that UniGetUI shows the UAC prompt first. An `.msi` is
installed for every user, behind the UAC prompt, unless it is a per-user package
(no `ALLUSERS`, or `ALLUSERS=2` with `MSIINSTALLPERUSER=1`) or the manifest gives `user`.

The manifest is read with the file: changing it is enough, no restart needed.

## Publish a package

**Folder or share feed:** copy the installer, and its manifest if it needs one, into the folder.

**Web feed:** copy the files into the folder you publish, then regenerate its index and upload the folder:

```powershell
& "$env:ProgramFiles\UniGetUI\UniGetUI.exe" pkg-index D:\publish\windows
```

The command reads every `.exe` and `.msi` in the folder, with their manifests, and writes
`index.json` next to them, with each package's identity, version, silent switches and SHA-256.
Run it again after every change. A file it cannot read is reported and left out of the index.

A folder can hold the packages of both platforms. Run `pkg-index` on Windows for the `.exe` and
`.msi` files and on a Mac for the `.pkg`, `.dmg` and `.zip` files: each keeps the entries the other
wrote, as long as those files are unchanged. Windows entries are listed separately in `index.json`,
so Macs, including those on older UniGetUI releases, never offer a Windows installer, and Windows
never offers a Mac package.

Each package shows the icon of its installer: an `.exe`'s own icon, or the product icon an `.msi`
gives Apps and Features (`ARPPRODUCTICON`, else its first shortcut's icon). To use another icon,
put a `.png`, `.jpg` or `.ico` with the same name next to the file (`Zoom.exe` → `Zoom.png`).

To offer an update, publish the newer file. When the feed holds several versions of a package,
users get the newest one that runs on their computer, and a native build is preferred: on an Arm
computer an `arm64` build wins over an `x64` one, which wins over an `x86` one.

## What users see

- **Install** and **Update** copy the installer from the share (or download it), check its hash,
its identity and its signature, then run it silently. An installer for every user asks for
administrator rights through the UAC prompt; a per-user one installs without it. Once it runs it
cannot be canceled.
- **Uninstall** runs what the app registered in Apps and Features, made silent: `msiexec /x` for an
`.msi`, the app's silent uninstall command when it registers one, else its uninstaller with the
switches of its technology or of the manifest. An app UniGetUI cannot uninstall silently is refused.
- Some installers register a slightly different version than their own (with a build number added
or dropped). After UniGetUI installs a package, it remembers which version that left, so the same
update is not offered again.
- When the feed is unreachable (off the VPN, share not reachable), UniGetUI keeps showing the
packages it last listed. Installing needs the feed again.

## Limits

- An `.msi` must be a single file: one that installs from a cabinet beside it (`data1.cab`) or from
uncompressed files is skipped, with the reason shown by **Check feed** and `pkg-index`.
- An `.exe` without a version in its version resource needs `version` in its manifest.
- An `.exe` is recognized by name only when the manifest gives no `uninstallKey`, so an app renamed
in Apps and Features is not recognized without it.
- When the name matches only once a version is removed from it (`Microsoft .NET SDK 8.0.133`), the
entry must share the package's major version. Products installed side by side within one major
version (SDK feature bands, runtimes) cannot be told apart by name: give them an `uninstallKey`
or `upgradeCode`.
- InstallShield and other installers have no standard silent switches; their manifest must give them.
- There is no helper service as on macOS: an installer for every user always asks for administrator rights.
3 changes: 3 additions & 0 deletions src/Languages/lang_en.json
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,7 @@
"Catalog Editor is disabled": "Catalog Editor is disabled",
"Enable the Catalog Editor in Experimental settings and developer options, then restart UniGetUI.": "Enable the Catalog Editor in Experimental settings and developer options, then restart UniGetUI.",
"Apps (.pkg and .dmg) that your organization publishes in its software catalog.": "Apps (.pkg and .dmg) that your organization publishes in its software catalog.",
"Apps (.exe and .msi) that your organization publishes in its software catalog.": "Apps (.exe and .msi) that your organization publishes in its software catalog.",
"Installer package (.pkg)": "Installer package (.pkg)",
"Disk image (.dmg)": "Disk image (.dmg)",
"Zip archive (.zip)": "Zip archive (.zip)",
Expand All @@ -265,9 +266,11 @@
"{0} packages found, {1} files skipped.": "{0} packages found, {1} files skipped.",
"The feed could not be read: {0}": "The feed could not be read: {0}",
"Every .pkg, .dmg and .zip file in this folder or web address appears in the catalog. Leave it empty for a catalog without a feed.": "Every .pkg, .dmg and .zip file in this folder or web address appears in the catalog. Leave it empty for a catalog without a feed.",
"Every .exe and .msi file in this folder or web address appears in the catalog. Leave it empty for a catalog without a feed.": "Every .exe and .msi file in this folder or web address appears in the catalog. Leave it empty for a catalog without a feed.",
"Package feed location": "Package feed location",
"Choose folder...": "Choose folder...",
"Allow packages that are not signed and notarized (for your own packages; keep the feed where only administrators can change it)": "Allow packages that are not signed and notarized (for your own packages; keep the feed where only administrators can change it)",
"Allow installers without a valid Authenticode signature (for your own packages; keep the feed where only administrators can change it)": "Allow installers without a valid Authenticode signature (for your own packages; keep the feed where only administrators can change it)",
"Check feed": "Check feed",
"Package feed": "Package feed",
"Choose the folder of the package feed": "Choose the folder of the package feed",
Expand Down
6 changes: 6 additions & 0 deletions src/UniGetUI.Avalonia.slnx
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,12 @@
<Platform Solution="*|x64" Project="x64" />
</Project>
</Folder>
<Folder Name="/UniGetUI.PackageEngine.Managers.Generic.InstallerFeeds/">
<Project Path="UniGetUI.PackageEngine.Managers.Generic.InstallerFeeds/UniGetUI.PackageEngine.Managers.Generic.InstallerFeeds.csproj">
<Platform Solution="*|arm64" Project="arm64" />
<Platform Solution="*|x64" Project="x64" />
</Project>
</Folder>
<Folder Name="/UniGetUI.PackageEngine.Managers.Generic.NuGet/">
<Project Path="UniGetUI.PackageEngine.Managers.Generic.NuGet/UniGetUI.PackageEngine.Managers.Generic.NuGet.csproj">
<Platform Solution="*|arm64" Project="arm64" />
Expand Down
Loading
Loading