Mirrors/velopack
1
0
Fork 0
mirror of https://github.com/velopack/velopack.git synced 2025-10-25 15:19:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

minor doc tweaks

Browse Source
This commit is contained in:
Caelan Sayler
2024-02-13 15:48:08 +00:00
parent 16e08adc01
commit ca933dcfe7
4 changed files with 30 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docfx/docs/distributing/overview.md
View File

@@ -1 +1,5 @@
*Applies to: Windows, MacOS, Linux*
# Distributing Overview
WIP

16
docfx/docs/index.md
View File

@@ -9,18 +9,16 @@ To enable your application to make full use of Velopack, you need to do 3 things
0. Run the `vpk` command line tool to generate your update packages and installers. [[Read more]](packaging/overview.md)
0. Upload your release somewhere your app can download updates from. [[Read more]](distributing/overview.md)
> [!TIP]
> If you are migrating an application from Squirrel.Windows or Clowd.Squirrel, you may also want to read [the migrating guide](migrating.md).
## Quick Start
- [C# .NET Quick Start](getting-started/csharp.md)
- Sample App: [Avalonia Cross Platform](https://github.com/velopack/velopack/tree/master/examples/AvaloniaCrossPlat)
- Sample App: [WPF / .Net Framework](https://github.com/velopack/velopack/tree/master/examples/VeloWpfSample)
## FAQ
- **My application was detected as a virus?** <br/>
Velopack can't help with this, but you can [code-sign](packaging/signing.md) your app and check [other suggestions here](https://github.com/clowd/Clowd.Squirrel/issues/28#issuecomment-1016241760).
- **What happened to SquirrelAwareApp? / Shortcuts** <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 reating 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.
Yes, this is fully supported. Before installing updates, Velopack will prompt the user to install any missing updates.
- **How do I install the `vpk` tool? / I've installed the tool but it doesn't work**
For now, you need to install `dotnet` runtime 6.0 or 8.0 for your platform, and then run `dotnet tool update -g vpk`.
If you get a message that it was installed successfully, but running it in your terminal results in a "binary/command not found" message,
it's probably because your PATH is not set-up properly. For windows, `%USERPROFILE%\.dotnet\tools` should be on the PATH. For macos, [see this issue](https://github.com/dotnet/sdk/issues/9415).
- **Can I use a 4 part version (1.0.0.0) instead of SemVer2?**
Velopack only supports a 3 part version with tags and metadata following (1.0.0-build.23+metadata), following the SemVer2 standard. Some people choose to version with the date, 2024.01.12 for example. It's also possible to get automated git commit based versioning [using something like nbgv](https://github.com/dotnet/Nerdbank.GitVersioning). The reason Velopack supports SemVer2 and not traditional 4 part versions is that it's possible to provide a lot more information in SemVer2 versions, and it is not feasible for us to support both formats throughout the framework.

2
docfx/docs/updating/hooks.md
View File

@@ -6,7 +6,7 @@ In general, I don't recommend trying to handle hooks manually - and instead refe
If you wish to handle these yourself, an SDK doesn't exist for your language, or you just want to learn more about it, read on.
## Command line hooks
At various stages of the install/update/uninstall process, Velopack will execute your main executable with certain cli arguments and expect your app to exit as quickly as possible.
At various stages of the install/update/uninstall process, Velopack will execute your main executable (the one specified when packaging with `--mainExe {exeName}`) with certain cli arguments and expect your app to exit as quickly as possible.
- `--veloapp-install {version}` Occurs after the program has been extracted, but before the install has finished. App must handle and exit within 30 seconds.
- `--veloapp-obsolete {version}` Runs on the old version of the app, before an update is applied. App must handle and exit within 15 seconds.

20
docfx/docs/updating/overview.md
View File

@@ -8,7 +8,7 @@ For .NET applications, you should first install the [Velopack Nuget Package](htt
## Application Startup
Velopack requires you add some code to your application startup to handle hooks. This is because Velopack will run your main binary at certain stages of the install/update process with special arguments, to allow you to customise behavior. It expects your app to respond to these arguments in the right way and then exit as soon as possible.
The simplest/minimal way to handle this properly is to add the SDK startup code to your `Main()` method.
The simplest/minimal way to handle this properly is to add the SDK startup code to your `Main()` method. This should be in the "main" binary (the one specified when packaging with `--mainExe {exeName}`).
```cs
static void Main(string[] args)
@@ -87,4 +87,20 @@ If you do not want to exit your app immediately, you can call `WaitExitThenApply
Lastly, if you do not call any of these "Apply" methods, when you re-launch your app, by default, Velopack will detect that there is a pending update and install it then. If you wish to disable this, you should call `VelopackApp.Build().SetAutoApplyOnStartup(false)`.
> [!TIP]
> It is recommended that you use one of the functions which explicitly applies a package (eg. `ApplyUpdatesAndRestart`), and do not rely on the AutoApply behavior as a rule of thumb. The auto behavior will only apply a downloaded version if it is > the currently installed version, so will not work if trying to downgrade or switch channels, and if more than one instance of your process is running it could result in the update failing or those other processes being terminated.
> It is recommended that you use one of the functions which explicitly applies a package (eg. `ApplyUpdatesAndRestart`), and do not rely on the AutoApply behavior as a rule of thumb. The auto behavior will only apply a downloaded version if it is > the currently installed version, so will not work if trying to downgrade or switch channels, and if more than one instance of your process is running it could result in the update failing or those other processes being terminated.
## How updates work
In a typical Windows install the application structure will look like this:
```
%LocalAppData%
└── {packId}
├── current
│ ├── YourFile.dll
│ ├── sq.version
│ └── YourApp.exe
└── Update.exe
```
`sq.version` is a special file created by Velopack which contains some metadata about your currently installed application. During install/uninstall, the entire `{packId}` folder is replaced or removed. During updates, only the `current` folder is replaced. If you store settings in the same folder as your main binary, they will be erased during updates.
If you want to create files that persist through updates, but are erased when the app is uninstalled, you should store them one level up (`..`) outside of the `current` dir. If you want to create files which persist even if the app is uninstalled (eg. important user settings) then you should store them in `%AppData%\{packId}` (that's the roaming app data, not local app data).