mirror of
https://github.com/velopack/velopack.git
synced 2025-10-25 15:19:22 +00:00
Adding documentation
This commit is contained in:
Caelan Sayler
@@ -15,7 +15,7 @@ Velopack is a setup / installation framework for cross-platform dotnet applicati
|
||||
|
||||
## Features
|
||||
|
||||
- 😍 **Zero config** – Velopack takes your dotnet build output (eg. `dotnet publish`), and generates an installer, and update package in a single command.
|
||||
- 😍 **Zero config** – Velopack takes your dotnet build output (eg. `dotnet publish`), and generates an installer, and updates and delta packages in a single command.
|
||||
- 🎯 **Cross platform** – Velopack supports building packages for **Windows**, **OSX**, and **Linux**. No matter your target, Velopack can create a release in just one command.
|
||||
- 🚀 **Automatic migrations** - If you are coming from [Squirrel.Windows](https://github.com/Squirrel/Squirrel.Windows) or [Clowd.Squirrel](https://github.com/clowd/Clowd.Squirrel), Velopack will automatically migrate your application. Just build your Velopack release and deploy! [Read more.](docs/migrating.md)
|
||||
- ⚡️ **Lightning fast** – Velopack is written in Rust for native performance. Creating releases is multi-threaded, and produces delta packages for ultra fast app updates. Applying update packages is highly optimised, and often can be done in the background.
|
||||
@@ -42,7 +42,7 @@ This is a very simple example of the steps you would take to generate an install
|
||||
4. Publish dotnet and build your first Velopack release! 🎉
|
||||
```cmd
|
||||
dotnet publish -c Release --self-contained -r win-x64 -o .\publish
|
||||
vpk pack -u YourAppId -v 1.0.0 -p .\publish
|
||||
vpk pack -u YourAppId -v 1.0.0 -p .\publish -e yourMainApp.exe
|
||||
```
|
||||
5. Add automatic updating to your app:
|
||||
```cs
|
||||
|
||||
72
docs/bootstrapping.md
Normal file
72
docs/bootstrapping.md
Normal file
@@ -0,0 +1,72 @@
|
||||
| [docs](.) / bootstrapping.md |
|
||||
|:---|
|
||||
|
||||
# Bootstrapping
|
||||
*Applies to: Windows*
|
||||
|
||||
While installing Velopack applications on Windows, it is possible to install other commonly required runtime dependencies using the `--framework` / `-f` argument.
|
||||
|
||||
It is possibly to specify more than one requirement, using a comma delimited list. For example:
|
||||
```cmd
|
||||
vpk pack ... --framework net6.0-x64-desktop,vcredist142-x64
|
||||
```
|
||||
|
||||
These dependencies will be downloaded and installed before your application can be installed.
|
||||
|
||||
## Adding dependencies during updates
|
||||
|
||||
Velopack will check that all required dependencies are installed before applying new updates. This means if a new version of your app adds a new dependency, the user will be prompted to install it before your new version is applied.
|
||||
|
||||
## List of supported frameworks
|
||||
|
||||
### vcredist
|
||||
- vcredist100-x86
|
||||
- vcredist100-x64
|
||||
- vcredist110-x86
|
||||
- vcredist110-x64
|
||||
- vcredist120-x86
|
||||
- vcredist120-x64
|
||||
- vcredist140-x86
|
||||
- vcredist140-x64
|
||||
- vcredist141-x86
|
||||
- vcredist141-x64
|
||||
- vcredist142-x86
|
||||
- vcredist142-x64
|
||||
- vcredist143-x86
|
||||
- vcredist143-x64
|
||||
- vcredist143-arm64
|
||||
|
||||
### .Net Framework
|
||||
- net45
|
||||
- net451
|
||||
- net452
|
||||
- net46
|
||||
- net461
|
||||
- net462
|
||||
- net47
|
||||
- net471
|
||||
- net472
|
||||
- net48
|
||||
- net481
|
||||
|
||||
### dotnet
|
||||
Every version of dotnet is supported >= 5.0. The framework argument should be supplied in the format `$"net{major.minor}-{arch}-{type}"`.
|
||||
|
||||
The valid `{arch}` values are
|
||||
- x86
|
||||
- x64
|
||||
- arm64
|
||||
|
||||
The valid `{type}` values are
|
||||
- runtime
|
||||
- aspnetcore
|
||||
- desktop
|
||||
|
||||
Here are some examples:
|
||||
- .NET 6.0 Desktop Runtime (x64) `--framework net6.0-x64-desktop`
|
||||
- .NET 8.0 Runtime (arm64) `--framework net8.0-arm64-runtime`
|
||||
- .NET 5.0 AspNetCore (x86) `--framework net5.0-x86-aspnetcore`
|
||||
|
||||
By default, Velopack will accept any installed release, but always install the latest. That is to say, if your dependency is specified as `net6.0-x64-desktop` and version `6.0.2` is installed, it will be accepted. If it's not installed, Velopack will download the latest available version (at the time of writing, that's `6.0.26`).
|
||||
|
||||
If you need a specific version of dotnet, (eg. `6.0.11`) - you can specify a third version part in your dependency string: `--framework net6.0.11-x64-desktop`. In this case, if the installed version is `<= 6.0.11`, then it will be upgraded to the latest available.
|
||||
@@ -7,7 +7,7 @@
|
||||
All parts of Velopack have logging built in to help troubleshoot issues, and you should provide these logs when opening a GitHub issue about a potential bug.
|
||||
|
||||
### UpdateManager / In your application
|
||||
You should provide an instance of `Microsoft.Extensions.Logging.ILogger` to `VelopackApp` and to `UpdateManager` to record potential issues. If you are not using Microsoft Hosting or Logging already, it is very simple to implement this interface yourself and log to a file, or integrate with another logging framework.
|
||||
You should provide an instance of `Microsoft.Extensions.Logging.ILogger` to `VelopackApp.Run(ILogger)` and to `UpdateManager` to record potential issues. If you are not using Microsoft Hosting or Logging already, it is very simple to implement this interface yourself and log to a file, or integrate with another logging framework.
|
||||
|
||||
For example:
|
||||
```cs
|
||||
|
||||
@@ -1 +1,69 @@
|
||||
tbc
|
||||
| [docs](.) / migrating.md |
|
||||
|:---|
|
||||
|
||||
# Migrating to Velopack
|
||||
*Applies to: Windows*
|
||||
|
||||
## Squirrel.Windows and Clowd.Squirrel
|
||||
If you are using one of these packages in your application, migrating will be mostly automated. Here are the general steps needed:
|
||||
|
||||
1. Replace the `Squirrel.Windows` or `Clowd.Squirrel` nuget package with the latest [`Velopack NuGet Package`](https://www.nuget.org/packages/velopack).
|
||||
|
||||
0. Install the `vpk` command line tool, as this is what you'll use to build Velopack releases.
|
||||
```cmd
|
||||
dotnet tool install -g vpk
|
||||
```
|
||||
|
||||
0. You will need to replace `SquirrelAwareApp` at the beginning of your app to `VelopackApp.Build().Run()`. Shortcuts [[Read more]](shortcuts.md) and registry entries are managed automatically for you in Velopack, so if you are currently doing this in `SquirrelAwareApp` hooks they should be removed. For example, if your hooks were this before:
|
||||
```cs
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
SquirrelAwareApp.HandleEvents(
|
||||
onInitialInstall: OnAppInstall,
|
||||
onAppUninstall: OnAppUninstall,
|
||||
onEveryRun: OnAppRun);
|
||||
}
|
||||
|
||||
private static void OnAppInstall(SemanticVersion version, IAppTools tools)
|
||||
{
|
||||
tools.CreateShortcutForThisExe(ShortcutLocation.StartMenu | ShortcutLocation.Desktop);
|
||||
}
|
||||
|
||||
private static void OnAppUninstall(SemanticVersion version, IAppTools tools)
|
||||
{
|
||||
tools.RemoveShortcutForThisExe(ShortcutLocation.StartMenu | ShortcutLocation.Desktop);
|
||||
}
|
||||
|
||||
private static void OnAppRun(SemanticVersion version, IAppTools tools, bool firstRun)
|
||||
{
|
||||
if (firstRun) MessageBox.Show("Thanks for installing my application!");
|
||||
}
|
||||
```
|
||||
Then you would migrate to the following code, removing the shortcut hooks:
|
||||
```cs
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
VelopackApp.Build()
|
||||
.WithFirstRun(v => MessageBox.Show("Thanks for installing my application!"))
|
||||
.Run();
|
||||
}
|
||||
```
|
||||
|
||||
0. The concept of `SquirrelAwareApp` no longer exists, so if you've added any attributes, assembly manifest entries, or other files to indicate that your binary is now aware, you can remove that. Every Velopack package has exactly one "VelopackApp" binary, which must implement the above interface at the top of `Main`. By default, Velopack will search for a binary in `{packDir}\{packId}.exe`. If your exe is named differently, you should provide the name with the `--mainExe yourApp.exe` argument.
|
||||
|
||||
0. The "RELEASES" file is no longer a format that Velopack uses, but it will produce one when building packages on windows with the default channel (eg. no channel argument provided). Instead, Velopack will produce `releases.{channel}.json` files, which should be treated in the same way. If you are wishing for a legacy windows app to migrate to Velopack, you should upload both the `RELEASES` file and the `releases.win.json` file which is produced by Velopack to your update feed.
|
||||
|
||||
0. In general, the command line supports all of the same features, but argument names or commands may have changed. Velopack no longer supports taking a `.nupkg` which was created by dotnet or nuget.exe. You should publish your app, and use `vpk pack` instead. A very simple example might look like this
|
||||
```cmd
|
||||
dotnet publish --self-contined -r win-x64 -o publish
|
||||
vpk pack -u YourAppId -v 1.0.0 -p publish -e yourMainBinary.exe
|
||||
```
|
||||
|
||||
Please review the vpk command line help for more details:
|
||||
```cmd
|
||||
vpk -h
|
||||
```
|
||||
|
||||
|
||||
## ClickOnce
|
||||
There is no guide or advice for migrating ClickOnce applications yet. If you would like to contribute one, please open an issue or PR!
|
||||
@@ -4,19 +4,25 @@
|
||||
# Velopack Documentation
|
||||
🚧🚧This documentation is still under construction.🚧🚧
|
||||
|
||||
## General
|
||||
- [FAQ](#faq)
|
||||
## FAQ
|
||||
- **My application was detected as a virus?** <br/>
|
||||
Velopack can't help with this, but you can [code-sign](signing.md) your app and check [other suggestions here](https://github.com/clowd/Clowd.Squirrel/issues/28#issuecomment-1016241760).
|
||||
- **What happened to SquirrelAwareApp?** <br/>
|
||||
This concept no longer exists in Velopack. You can create hooks on install/update in a similar way using the `VelopackApp` builder. Although note that creating shortcuts or registry entries yourself during hooks is no longer required.
|
||||
- **Can Velopack bootstrap new runtimes during updates?** <br/>
|
||||
Yes, this is fully supported. Before installing updates, Velopack will prompt the user to install any missing updates.
|
||||
|
||||
## Using Velopack
|
||||
- [Migrating to Velopack](migrating.md)
|
||||
- [Logging & Debugging](debugging.md)
|
||||
- [Command Line Reference](cli.md)
|
||||
|
||||
## Using Velopack
|
||||
- Packaging Releases
|
||||
- Overview
|
||||
- Release Channels & RID's
|
||||
- Release Channels
|
||||
- Installer Overview & Customisation
|
||||
- [Code Signing](signing.md)
|
||||
- Boostrapping frameworks (.NET, .Net Framework, VCRedist, etc)
|
||||
- [Boostrapping frameworks (.NET, .Net Framework, VCRedist, etc)](bootstrapping.md)
|
||||
- Specify app RID / supported OS versions / supported architecture
|
||||
- Distributing Releases
|
||||
- Overview
|
||||
- CI / CD Tips & Examples
|
||||
@@ -24,14 +30,6 @@
|
||||
- Deploying to Amazon S3 Storage (or compatible, eg. B2, Linode)
|
||||
- Updating
|
||||
- Overview
|
||||
- Partial roll-out (A/B testing)
|
||||
- Rolling back to a previous release
|
||||
- Windows Shortcuts
|
||||
|
||||
## FAQ
|
||||
- **My application was detected as a virus?** <br/>
|
||||
Velopack can't help with this, but you can [code-sign](signing.md) your app and check [other suggestions here](https://github.com/clowd/Clowd.Squirrel/issues/28#issuecomment-1016241760).
|
||||
- **What happened to SquirrelAwareApp?** <br/>
|
||||
This concept no longer exists in Velopack. You can initialise hooks on install/update in a similar way using the `VelopackApp` builder.
|
||||
- **Can Velopack bootstrap new runtimes during updates?** <br/>
|
||||
Yes, this is fully supported. Before installing updates, Velopack will prompt the user to install any missing updates.
|
||||
- [Windows Shortcuts](shortcuts.md)
|
||||
- Customising updates (AfterInstall, BeforeUninstall, BeforeUpdate, AfterUpdate hooks)
|
||||
|
||||
13
docs/shortcuts.md
Normal file
13
docs/shortcuts.md
Normal file
@@ -0,0 +1,13 @@
|
||||
| [docs](.) / shortcuts.md |
|
||||
|:---|
|
||||
|
||||
# Windows Shortcuts
|
||||
*Applies to: Windows*
|
||||
|
||||
By default, during installation Velopack will create a shortcut on the Desktop and in the Start Menu Root.
|
||||
|
||||
It will automatically delete any shortcuts it finds when uninstalling the application.
|
||||
|
||||
If you need to create shortcuts in any extra locations, the `Velopack.Windows.Shortcuts` and `Velopack.Windows.ShellLink` classes are provided.
|
||||
|
||||
These classes are provided for legacy reasons, and in general the stability of such functions is not guarenteed.
|
||||
@@ -2,10 +2,44 @@
|
||||
|:---|
|
||||
|
||||
# Code Signing
|
||||
*Applies to: Windows, MacOS*
|
||||
|
||||
Code signing is an essential part of application distribution. On Windows, applications without code signatures are likely to be flagged as viruses. On OSX, codesigning and Notarization is required before your application can be run by users.
|
||||
|
||||
On both platforms, signing needs to be performed by Velopack itself, this is because the Velopack binaries (such as Update and Setup) need to be signed at different points in the package build process.
|
||||
|
||||
## Signing on Windows
|
||||
tbc
|
||||
|
||||
### Acquiring a code signing certificate
|
||||
First, you need to acquire a code-signing certificate from a reputable brand. To name a few: Digicert, Sectigo, Comodo. It may be possible to purchase a certificate through an official reseller for cheaper than buying directly from the issuer. If you are looking for an open source development certificate, Certum currently does an [Open Source Cloud Signing](https://certum.store/data-safety/code-signing-certificates.html?as_dane_w_certyfikacie=5720) certificate for $58
|
||||
|
||||
**Disclaimer: This is by no means a recommendation or advice for any particular code-signing certificate issuer, but instead is general guidance for the process one might follow to purchase a certificate.**
|
||||
|
||||
### Signing via `signtool.exe`
|
||||
usually signing is accomplished via `signtool.exe`. If you already use this tool to sign your application, you can just lift your sign parameters straight to Velopack.
|
||||
|
||||
For example, if your signing command before was:
|
||||
```cmd
|
||||
signtool.exe sign /td sha256 /fd sha256 /f yourCert.pfx /tr http://timestamp.comodoca.com
|
||||
```
|
||||
|
||||
Then now with `--signParams` it would be:
|
||||
```cmd
|
||||
vpk pack ... --signParams "/td sha256 /fd sha256 /f yourCert.pfx /tr http://timestamp.comodoca.com"
|
||||
```
|
||||
|
||||
If you are new to using `signtool.exe`, you can check the [command line reference here](https://learn.microsoft.com/en-us/dotnet/framework/tools/signtool-exe). I recommend getting signing working on a single binary first, using `signtool.exe`, before trying to get things working with the Velopack CLI.
|
||||
|
||||
Take care when providing parameters that if you have any quoted (`"`) arguments you will need to escape those quotes with a backslash.
|
||||
|
||||
By default, Velopack will sign 10 files per call to `signtool.exe`, to speed up signing and reduce the number of times you need to interact with the console if you are using some kind of interactive signing method. This can be disabled with the `--signParallel 1` argument.
|
||||
|
||||
### Custom signing commands and tools
|
||||
If you have more advanced signing requirements, such as a custom signing tool (eg. `AzureSignTool.exe`), then you can provide a command template instead, where `{{file}}` is the binary that Velopack will substitute and sign:
|
||||
|
||||
```cmd
|
||||
vpk pack ... --signTemplate "AzureSignTool.exe sign ... {{file}}"
|
||||
```
|
||||
|
||||
## Signing & Notarizing on OSX
|
||||
Codesigning and Notarization is required before your application can be run by users, therefore it is a required step before deploying your application.
|
||||
|
||||
Reference in New Issue
Block a user