diff --git a/.gitignore b/.gitignore index bef7bb18..604d1209 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ -# Rust + target/ +_docyml/ ################# ## Eclipse diff --git a/docfx.json b/docfx.json new file mode 100644 index 00000000..f7c76a6b --- /dev/null +++ b/docfx.json @@ -0,0 +1,15 @@ +{ + "metadata": [ + { + "src": [ + { + "src": "src/Velopack", + "files": [ + "**/*.csproj" + ] + } + ], + "dest": "_docyml" + } + ] +} \ No newline at end of file diff --git a/docfx/.gitignore b/docfx/.gitignore deleted file mode 100644 index 1d556625..00000000 --- a/docfx/.gitignore +++ /dev/null @@ -1,7 +0,0 @@ -api/ -sdk/ -_site/ -templates/ -reference/ -ref/ -/toc.yml \ No newline at end of file diff --git a/docfx/README.md b/docfx/README.md deleted file mode 100644 index 5fcad633..00000000 --- a/docfx/README.md +++ /dev/null @@ -1,6 +0,0 @@ -## If you've reached this page, you're probably [looking for the Velopack documentation site](https://velopack.io/docs/). - -If you want to build and run the documentation site yourself locally, you can do so: -- Install docfx (`dotnet tool install -g docfx`) -- Run the site with `docfx --serve` -- Navigate to `http://localhost:8080/docs`. \ No newline at end of file diff --git a/docfx/docfx.json b/docfx/docfx.json deleted file mode 100644 index 5abf02c3..00000000 --- a/docfx/docfx.json +++ /dev/null @@ -1,48 +0,0 @@ -{ - "metadata": [ - { - "src": [ - { - "src": "../src/Velopack", - "files": [ - "**/*.csproj" - ] - } - ], - "dest": "ref/cs" - } - ], - "build": { - "content": [ - { - "files": [ - "**/*.{md,yml}" - ], - "exclude": [ - "_site/**", - "README.md" - ] - } - ], - "resource": [ - { - "files": [ - "images/**" - ] - } - ], - "output": "_site", - "template": [ - "default", - "modern", - "templates/velopack" - ], - "globalMetadata": { - "_appName": "Velopack", - "_appTitle": "Velopack", - "_enableSearch": true, - "_disableNextArticle": true, - "pdf": false - } - } -} \ No newline at end of file diff --git a/docfx/docs/compiling.md b/docfx/docs/compiling.md deleted file mode 100644 index 90e6f3e5..00000000 --- a/docfx/docs/compiling.md +++ /dev/null @@ -1,51 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Compiling Velopack -Velopack is made up of some Rust binaries which are re-distributed with installed apps, a .NET NuGet package, and a .NET command line tool. In order to test the project, you need to build the Rust binaries before compiling dotnet. - -### Prerequisites - - [.NET 6 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) - - [.NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) - - [Rust / Cargo](https://www.rust-lang.org/tools/install) - - `dotnet tool install -g dotnet-coverage` - - `dotnet tool install -g nbgv` - -### Debug / Test -On windows, you need to build the Rust binaries using the `windows` feature before running tests. On OSX, you should run `cargo build` instead. - -```shell -git clone https://github.com/velopack/velopack.git -cd velopack/src/Rust -cargo build --features windows -cd ../../ -dotnet build -dotnet test --no-build -``` - -### Release / Build -This is slightly complicated, because you will need to compile Rust on x64 OSX and x64 Windows before creating the final packages. - -On OSX: -```shell -git clone https://github.com/velopack/velopack.git -cd velopack/src/Rust -cargo build --release -``` - -On Windows: -```shell -git clone https://github.com/velopack/velopack.git -cd velopack/src/Rust -cargo build --release --features windows -copy {path_to_osx_update} target/release/updatemac -dotnet build -c Release /p:PackRustAssets=true -``` - -### Compiling on Linux -If you are on Linux (tested on Ubuntu), there are additional package pre-requisites: -```sh -sudo apt install libssl-dev pkg-config -``` -You need to verify that `nbgv` is working on the command line, you may be missing a `DOTNET_ROOT` variable in your bash profile, which might need to point at `/usr/share/dotnet` or `$HOME/.dotnet`. - -If you are missing localisation packages, you can search for them or add `export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1` to your bash profile. \ No newline at end of file diff --git a/docfx/docs/distributing/deploy-cli.md b/docfx/docs/distributing/deploy-cli.md deleted file mode 100644 index 4d84223d..00000000 --- a/docfx/docs/distributing/deploy-cli.md +++ /dev/null @@ -1,41 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Deployment CLI -The general process for deploying a Velopack release (`download -> pack -> upload`) can be greatly simplified by using the `download` and `upload` commands which are built into the `vpk` command line tool. - -## Packing your new release with delta's - -In order for delta's to be generated during the `pack` command, you need to first download the current latest release. This should be done with the download command: - -```cmd -vpk download http --url https://the.place/you-host/updates -vpk pack -u YourAppId -v 1.0.1 -p {buildOutput} -``` - -There are providers for various sources, such GitHub, S3, HTTP, etc. - -## Deploying releases -In the previous example, we used the `http` source, while that is very generic it does not provide any information about how to upload the releases, so in the following deployment example we will use [AWS S3](https://aws.amazon.com/s3/). - -> [!TIP] -> Most cloud storage providers today have an S3-compatible API ([GCP](https://cloud.google.com/storage/docs/interoperability), [BackBlaze B2](https://www.backblaze.com/docs/cloud-storage-s3-compatible-api), [DigitalOcean](https://docs.digitalocean.com/products/spaces/how-to/use-aws-sdks/), [Linode](https://www.linode.com/docs/products/storage/object-storage/), [IBM Cloud](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-compatibility-api), and so forth) and can be used with this command - it is not limited to AWS. - -Using AWS, you can [authenticate using the `aws` command line tool](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/creds-idc.html) or you can provide access keys as below. - -If you are using AWS SSO, you should check the [AWS CLI SSO](https://aws.amazon.com/blogs/security/aws-single-sign-on-now-enables-command-line-interface-access-for-aws-accounts-using-corporate-credentials/) doc and [AWS session authentication](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html). - -```cmd -vpk download s3 --bucket MyApp --region us-west-1 --keyId {accessKeyId} --secret {accessKeySecret} -vpk pack -u YourAppId -v 1.0.1 -p {buildOutput} -vpk upload s3 --bucket MyApp --region us-west-1 --keyId {accessKeyId} --secret {accessKeySecret} -``` - -Note that you can specify most of these argumentsas environment variables too. You can review the [AWS SDK environment variables here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) and every `vpk` option can be provided as an environment variable too, to list these in the help text use `vpk -H` instead of `vpk -h`. - -When using a non-AWS S3-compatible API (eg. BackBlaze B2), you need to specify an endpoint instead of a region: - -```cmd -vpk download s3 --bucket MyApp --endpoint https://s3.eu-central-003.backblazeb2.com --keyId {accessKeyId} --secret {accessKeySecret} -vpk pack -u YourAppId -v 1.0.1 -p {buildOutput} -vpk upload s3 --bucket MyApp --endpoint https://s3.eu-central-003.backblazeb2.com --keyId {accessKeyId} --secret {accessKeySecret} -``` diff --git a/docfx/docs/distributing/github-actions.md b/docfx/docs/distributing/github-actions.md deleted file mode 100644 index e53090c3..00000000 --- a/docfx/docs/distributing/github-actions.md +++ /dev/null @@ -1,114 +0,0 @@ -_Applies to: Windows_ - -# Continuous Deployment - -> [!NOTE] -> This page is a work in progress. While there is only information regarding GitHub Actions here currently, please note -that Velopack can be used with many different methods of Continuous Deployment. - -## GitHub Actions - -This section assumes you have a basic knowledge of GitHub Actions. You can learn more about -creating workflows [here](https://docs.github.com/en/actions/deployment/about-deployments/deploying-with-github-actions). - -### Creating the Workflow - -The following example assumes you are building for Windows, but you can adapt the workflow for other platforms as well. - -First create a workflow in your repository at `.github/workflows` with the `.yml` extension, for example -`.github/workflows/main.yml`. This example workflow will run when code is pushed to the `main` branch. Refer to -documentation linked above if you would prefer a different trigger. - -```yml -name: Deploy to GitHub Releases - -on: - push: - branches: - - main -``` - -Create the job that will run when the trigger is activated. This example will run on a `windows-latest` machine as we're -packaging for Windows. - -```yml -jobs: - deploy-to-github-releases: - runs-on: windows-latest - steps: -``` - -### Compiling the Application - -First, add a step to checkout your repository to get all the files needed to compile your application. - -```yml - - name: Checkout Repository - uses: actions/checkout@v4 -``` - -You will need the version number of your release for packing with Velopack. There are many ways to handle this. -If you are using GitHub Action variables to handle this, you can skip this step. This example will extract the -version number from the `` tag in the `.csproj` of the application. The `bash` shell is defined here -as this command will fail when running on Windows otherwise. The command works by using a regular expression -with `grep` to extract the value between `` and `` in the csproj file, and store it in a -variable called `version` in the current run of the workflow. - -```yml - - name: Get Version from Project File - id: get-version - shell: bash - run: echo "version=$(grep -oE '[^<]+' MyApplication/MyApplication.csproj | sed 's///')" >> $GITHUB_OUTPUT -``` - -Next, add a step to install .NET so the application can be compiled. Set the `dotnet-version` to the version needed by -your application. - -```yml - - name: Install .NET - uses: actions/setup-dotnet@v4 - with: - dotnet-version: 8.0.x -``` - -Compile your application. This example will do so by publishing the application to a folder in a self-contained manner. -You can publish without the self-contained flag if using Velopack to install such dependencies -(see [Bootstrapping](../packaging/bootstrapping.md) for details). This command uses the `-c` flag to set the build -configuration to `Release` mode, `-o` to set the output directory to `publish`, `-r` to set the runtime -to `win-x64` for distributing on 64-bit Windows, and `--self-contained` to publish the .NET runtime with the -application. Adapt this command to your needs. You can learn more about -`dotnet publish` in the [Microsoft Documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-publish). - -```yml - - name: Publish Application - run: dotnet publish MyProject/MyProject.csproj -c Release -o publish -r win-x64 --self-contained true -``` - -### Deploying the Release - -Finally, use Velopack to package your application and deploy your release. Create a step that runs several commands -on the commandline. - -Let's break down what each line does. - -1. Installs the Velopack CLI. -2. Downloads the latest release of your repository. This is needed so that Velopack can create the delta package -between the current release and the new one, as well as populating the releases files. -3. Invokes the Velopack CLI to package your application. The `-v` argument calls upon -the `version` variable assigned earlier, which is accessed using the `id` of the step that assigned it (`get-version`). -`-p` is pointed at the `publish` directory that was used in the previous step. For more information on the Velopack CLI -and which flags are available for the `pack` command, [see here](../packaging/overview.md). -4. Creates a new release in your repository and uploads the necessary files to it automatically. - -> [!NOTE] -> If your repository is private, you will need to provide Velopack with an OAuth token when using the `vpk download` -and `vpk upload` commands. Simply append the following to both commands: `--token ${{ secrets.GITHUB_TOKEN }}`. - -```yml - - name: Create Velopack Release - run: | - dotnet tool install -g vpk - vpk download github --repoUrl https://github.com/Myname/Myrepo - vpk pack -u MyUniqueIdentifier -v ${{ steps.get-version.outputs.version }} -p publish - vpk upload github --repoUrl https://github.com/Myname/Myrepo --publish --releaseName "MyProject ${{ steps.get-version.outputs.version }}" --tag v${{ steps.get-version.outputs.version }} -``` \ No newline at end of file diff --git a/docfx/docs/distributing/overview.md b/docfx/docs/distributing/overview.md deleted file mode 100644 index cbbd502e..00000000 --- a/docfx/docs/distributing/overview.md +++ /dev/null @@ -1,85 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Distributing Overview -Distributing with Velopack is extremely easy, it's usually just as simple as uploading your files somewhere that can be downloaded with HTTP. This means you could host them on an IIS or nodejs site, on shared file hosting such as AWS S3, Azure Storage, BackBlaze B2, or even for free on GitHub/GitLab releases if your project is open source. - -The general steps for creating and deploying a Velopack release are: -1. Download the latest published release (eg. 1.0.0). -0. Run `vpk pack` to create your new release (eg. 1.0.1). -0. Upload your newly created 1.0.1 assets. -0. Update the remote releases.{channel}.json to reflect the newly uploaded assets. - -See also: [Deployment commands](deploy-cli.md) can make this process much easier. - -## List of assets produced -After packing a release with Velopack, you should have something like the following in your output directory: - -``` -Releases -├── YourAppId-1.0.1-full.nupkg -├── YourAppId-1.0.1-delta.nupkg -├── YourAppId-Setup.exe -├── YourAppId-Portable.zip -├── releases.{channel}.json -├── assets.{channel}.json -└── RELEASES -``` - -### Full and delta nupkg's -These are the update packages that installed applications use to find/install the latest version. Full packages contain an entire replication of your input files, plus some files Velopack adds. A delta package is a diff from the previously created full package. You need to have the previous version (eg. 1.0.0 in the above example) downloaded and in the output directory for a delta to be created (in this case, `1.0.0->1.0.0`). There are helpful [deployment commands](deploy-cli.md) which can download the latest version for you, so that deltas will be generated automatically. - -You must distribute these packages in the same folder as the `releases.{channel}.json` file for updates to work. - -### Setup and portable -This is what your user should download and run to install your app. On MacOS, you'll get a `.pkg` instead of a `-Setup.exe`. On Linux, there is no setup produced - only a portable `.AppImage`. The reason for this is that `.AppImage`'s are completely portable to any relatively recent distro of linux. - -### Release feed (`releases.{channel}.json`) -This file should be distributed in the same folder as the `nupkg` files are deployed. It contains a list of all available releases. - -When you provide a HTTP url to `UpdateManager`, it will search for this file. For example, if you `new UpdateManager("https://the.place/you-host/updates")`, then UpdateManager will request for `https://the.place/you-host/updates/releases.{channel}.json`. The channel UpdateManager uses in the request is automatic, you can [read more here about channels](../packaging/channels.md). - -For example, if you packed `1.0.0` and then `1.0.1` immediately after, the contents of this file might look like: - -```json -{ - "Assets": [ - { - "PackageId": "YourAppId", - "Version": "1.0.1", - "Type": "Full", - "FileName": "YourAppId-1.0.1-full.nupkg", - "SHA1": "537EC0F4E1C4263A230353FAB4150216E5AF3724", - "Size": 1588612 - }, - { - "PackageId": "YourAppId", - "Version": "1.0.1", - "Type": "Delta", - "FileName": "YourAppId-1.0.1-delta.nupkg", - "SHA1": "9615D266DDBCADF3B9CD82BABF9DA571A0EE2B83", - "Size": 3606 - }, - { - "PackageId": "YourAppId", - "Version": "1.0.0", - "Type": "Full", - "FileName": "YourAppId-1.0.0-full.nupkg", - "SHA1": "69122BABCEEEF9F653BFE59D87DDAEF363F9476F", - "Size": 1588613 - } - ] -} -``` - -The releases file should always mirror what files are _actually available_ in the remote folder that contains the releases file. So if you delete a nupkg release from the remote server, you should delete it from your remote release file too. If you are deploying newly created local files to a remote server which already contains some releases, then you should copy the assets from your local file to the remote releases file. - -> [!WARNING] -> This file is the only way that UpdateManager can discover releases, if you do not update it properly it may result in your users not getting updates. - -It is tedious to update this file manually, so Velopack CLI provides deployment commands which can deploy assets and update this file automatically for you, as well as apply rentention policies around the number of releases to keep. [[Read more]](deploy-cli.md) - -### Legacy release feed (`RELEASES`) -This releases format was used by Clowd.Squirrel and Squirrel.Windows, and is still produced by Velopack to allow you to migrate an application using one of those frameworks to Velopack. If you do not have any legacy users which need to migrate to Velopack, you can safely ignore this file. - -### Assets file -This file contains a list of assets produced by the latest `pack` command. It is used by the [Velopack deployment commands](deploy-cli.md) to know which files should be uploaded. It can be ignored / deleted if you do not intend to use these commands to deploy releases and automatically update your release feed. \ No newline at end of file diff --git a/docfx/docs/distributing/toc.yml b/docfx/docs/distributing/toc.yml deleted file mode 100644 index bd346d82..00000000 --- a/docfx/docs/distributing/toc.yml +++ /dev/null @@ -1,6 +0,0 @@ -- name: Overview - href: overview.md -- name: Deployment CLI - href: deploy-cli.md -- name: CI - Github Actions - href: github-actions.md \ No newline at end of file diff --git a/docfx/docs/getting-started/csharp.md b/docfx/docs/getting-started/csharp.md deleted file mode 100644 index 3bb59c0e..00000000 --- a/docfx/docs/getting-started/csharp.md +++ /dev/null @@ -1,46 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Getting Started: C# / .NET - -1. Install the command line tool `vpk`: - ```cmd - dotnet tool update -g vpk - ``` -2. Install the [Velopack NuGet Package](https://www.nuget.org/packages/velopack) in your main project: - ```cmd - dotnet add package Velopack - ``` -3. Configure your Velopack app at the beginning of `Program.Main`: - ```cs - static void Main(string[] args) - { - VelopackApp.Build().Run(); - // ... your other startup code below - } - ``` -4. Add automatic updating to your app: - ```cs - private static async Task UpdateMyApp() - { - var mgr = new UpdateManager("https://the.place/you-host/updates"); - - // check for new version - var newVersion = await mgr.CheckForUpdatesAsync(); - if (newVersion == null) - return; // no update available - - // download new version - await mgr.DownloadUpdatesAsync(newVersion); - - // install new version and restart app - mgr.ApplyUpdatesAndRestart(newVersion); - } - ``` -5. 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 -e yourMainApp.exe - ``` -6. Upload the files created by Velopack to `https://the.place/you-host/updates` - -If you're not sure how these instructions fit into your app, check the example apps for common scenarios such as WPF or Avalonia. \ No newline at end of file diff --git a/docfx/docs/getting-started/electron.md b/docfx/docs/getting-started/electron.md deleted file mode 100644 index 375cfe0e..00000000 --- a/docfx/docs/getting-started/electron.md +++ /dev/null @@ -1,73 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Getting Started: JS / Electron -This quick start is slightly tailored to Electron, so if you are using pure nodejs and bundling your app using [pkg](https://github.com/vercel/pkg) or similar you can ignore those steps. - -1. Add Velopack to your `package.json`: -```txt -npm install velopack -``` - -2. Add the following code to your entry point (eg. `index.js`) as early as possible (before any electron startup code etc.): -```js -const { VelopackApp } = require('velopack'); - -// Velopack builder needs to be the first thing to run in the main process. -// In some cases, it might quit/restart the process to perform tasks. -VelopackApp.build().run(); - -// ... your other app startup code here -``` - -3. Add auto-updates somewhere to your app: -```js -const { UpdateManager } = require('velopack'); - -async function updateApp() -{ - const um = new UpdateManager(); - um.setUrlOrPath("https://the.place/you-host/updates"); - - const updateInfo = await um.checkForUpdatesAsync(); - if (!updateInfo) { - return; // no update available - } - - await um.downloadUpdatesAsync(updateInfo.targetFullRelease, p => { - console.log(`progress: ${p}%`); - }); - - um.applyUpdatesAndRestart(updateInfo.targetFullRelease); -} -``` - -4. If you are using electron/forge, you will need to add an asar unpack rule: -```js -module.exports = { - packagerConfig: { - asar: { - // velopack contains native binaries which must remain unpacked - unpack: '**/node_modules/velopack/**', - }, - }, -} -``` - -5. Compile your app to a binary (eg. `.exe` on Windows). Example using electron forge: -```sh -npx electron-forge package -``` - -6. Install the `vpk` command line tool: -```sh -dotnet tool update -g vpk -``` -***Note: you must have the .NET Core SDK 6 installed to use and update the `vpk`*** - -7. Package your Velopack release / installers: -```sh -vpk pack -u MyAppUniqueId -v 1.0.0 -p /myBuildDir -e myexename.exe -``` - -✅ You're Done! Your app now has auto-updates and an installer. -You can upload your release to your website, or use the `vpk upload` command to publish it to the destination of your choice. \ No newline at end of file diff --git a/docfx/docs/getting-started/rust.md b/docfx/docs/getting-started/rust.md deleted file mode 100644 index e73b4ec3..00000000 --- a/docfx/docs/getting-started/rust.md +++ /dev/null @@ -1,53 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Getting Started: Rust - -1. Add Velopack to your `Cargo.toml`: -```toml -[dependencies] -velopack = { version = "0.0", features = ["async"] } # Replace with actual version and desired features -``` - -2. Add the following code to your `main()` function: -```rust -use velopack::*; -fn main() { - // VelopackApp should be the first thing to run - // In some circumstances it may terminate/restart the process to perform tasks. - VelopackApp::build().run(); - - // ... your other app startup code here -} -``` - -3. Add auto-updates somewhere to your app: -```rust -use velopack::*; -use anyhow::Result; -fn update_my_app() -> Result<()> { - let um = UpdateManager::new("https://the.place/you-host/updates", None)?; - let updates: Option = um.check_for_updates()?; - if updates.is_none() { - return Ok(()); // no updates available - } - let updates = updates.unwrap(); - um.download_updates(&updates, |progress| { - println!("Download progress: {}%", progress); - })?; - um.apply_updates_and_restart(&updates, RestartArgs::None)?; - Ok(()) -} -``` - -4. Build your app with cargo: -```sh -cargo build --release -``` - -5. Package your Velopack release / installers: -```sh -vpk pack -u MyAppUniqueId -v 1.0.0 -p /target/release -e myexename.exe -``` - -✅ You're Done! Your app now has auto-updates and an installer. -You can upload your release to your website, or use the `vpk upload` command to publish it to the destination of your choice. \ No newline at end of file diff --git a/docfx/docs/index.md b/docfx/docs/index.md deleted file mode 100644 index e50a4fc2..00000000 --- a/docfx/docs/index.md +++ /dev/null @@ -1,23 +0,0 @@ -# Documentation -Velopack is an installation and auto-update framework for cross-platform desktop applications. It's opinionated, extremely easy to use with zero config needed. With just one command you can be up and running with an installable application, and it's lightning fast for your users, too. - -Be sure to check us out on [GitHub](https://github.com/velopack/velopack) and [join our Discord](https://discord.gg/CjrCrNzd3F) for any questions/support! - -## Overview -To enable your application to make full use of Velopack, you need to do 3 things: -1. Add the SDK to your app, and check for updates. [[Read more]](updating/overview.md) -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) - -## FAQ -- **My application was detected as a virus?**
- 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**
- 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?**
- 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). In general, dotnet should set these paths up for you, but that is what you should check if things are not working. -- **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 (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. \ No newline at end of file diff --git a/docfx/docs/migrating.md b/docfx/docs/migrating.md deleted file mode 100644 index 3f00f46f..00000000 --- a/docfx/docs/migrating.md +++ /dev/null @@ -1,67 +0,0 @@ -*Applies to: Windows* - -# Migrating to Velopack - -## From 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]](updating/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 - ``` - - -## From 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! \ No newline at end of file diff --git a/docfx/docs/packaging/bootstrapping.md b/docfx/docs/packaging/bootstrapping.md deleted file mode 100644 index c9107a7b..00000000 --- a/docfx/docs/packaging/bootstrapping.md +++ /dev/null @@ -1,76 +0,0 @@ -*Applies to: Windows* - -# Bootstrapping -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 will be installed. - -> [!CAUTION] -> If you are building a dotnet application with `--self-contained`, you should **NOT** provide a `--framework` argument specifying that your app requires dotnet installed, because your application already has the runtime bundled in. If you are publishing your application with `--no-self-contained`, then you should provide the `--framework` argument. - -## 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 -Any of the following can be passed via the `--framework` argument. - -### Edge WebView2 -- `webview2` - -### vcredist -- `vcredist100-x86` (VC++ 10.0 / VS 2010) -- `vcredist100-x64` (VC++ 10.0 / VS 2010) -- `vcredist110-x86` (VC++ 11.0 / VS 2012) -- `vcredist110-x64` (VC++ 11.0 / VS 2012) -- `vcredist120-x86` (VC++ 12.0 / VS 2013) -- `vcredist120-x64` (VC++ 12.0 / VS 2013) -- `vcredist140-x86` (VC++ 14.0 / VS 2015) -- `vcredist140-x64` (VC++ 14.0 / VS 2015) -- `vcredist141-x86` (VC++ 14.1 / VS 2017) -- `vcredist141-x64` (VC++ 14.1 / VS 2017) -- `vcredist142-x86` (VC++ 14.2 / VS 2019) -- `vcredist142-x64` (VC++ 14.2 / VS 2019) -- `vcredist143-x86` (VC++ 14.3 / VS 2022) -- `vcredist143-x64` (VC++ 14.3 / VS 2022) -- `vcredist143-arm64` (VC++ 14.3 / VS 2022) - -### .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. \ No newline at end of file diff --git a/docfx/docs/packaging/channels.md b/docfx/docs/packaging/channels.md deleted file mode 100644 index bf0debc0..00000000 --- a/docfx/docs/packaging/channels.md +++ /dev/null @@ -1,36 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Release Channels -Channels is a fundemental part of how Velopack understands and builds releases. Every release must belong to a channel. If you do not specify a channel when building a release (via the `--channel`) argument, the default channel will be the name of the target Operating System (eg. `win`, `osx`, or `linux`). - -When building releases, Velopack will create a `releases.{channel}.json` file, that should be uploaded with your other assets (eg. `.nupkg`). This is how `UpdateManager` knows what releases are available. - -In general, you should not provide a channel to the `UpdateManager` constructor (leave it null). In this case, it will only search for update packages in the same channel that the current release was built for. For example, if you provided the `--channel stable` argument to `vpk`, and installed your app, then `UpdateManager` will automatically be searching for the file `releases.stable.json` when checking for updates. - -❗For legacy purposes, Velopack will also generate a `RELEASES` file (for the `win` channel), or a `RELEASES-{channel}` file (for any other channel). By deploying these files as well as the `releases.{channel}.json` will allow legacy apps to upgrade to Velopack. If you do not have any users on legacy versions of your software, you can ignore these files. - -## Switching channels in installed apps -It is often desirable to allow users to switch channels easily. For example, if your users downloaded an installer for a "stable" version of your app, they will only receive updates for the "stable" channel. Later on, they decide they wish to switch to the "beta" channel to try some experimental features in your app. - -This can be done by supplying a non-null channel argument to the UpdateManager constructor. So you would instantiate as `new UpdateManager("https://the.place/you-store/updates", "beta")` and then perform an update process as usual. - -## Deploying cross-platform apps - -It's important when deploying cross platform (or cross-architecture) apps that every unique os/rid has it's own channel. It wouldn't be good if your Windows app tried to install an OSX package etc! - -The default channels are, `win`, `osx`, or `linux`, so if you are only distributing one release per platform, you do not need to specify a channel argument, everything should work automatically. If you are distributing feature channels (eg. 'stable', 'beta') or need to distribute multiple versions of your app per os (eg. `win-x64`, `win-arm64`) then you will need to define a channel strategy that does not collide. - -For example, if I was distributing an app on windows and osx which needed to support x64, and arm64, and also needed to support "stable" and "beta", then I would need the following 8 channels: -- win-x64-stable -- win-x64-beta -- win-arm64-stable -- win-arm64-beta -- osx-x64-stable -- osx-x64-beta -- osx-arm64-stable -- osx-arm64-beta - -## Renaming a channel -You can't rename a channel per-say, but you can supercede it (ie. force all your users to switch to the new channel). Imagine you have been publishing an app that only supports x64 windows to the channel `stable` until now, but you now would like to release an arm64 version of your app. So you want to migrate all the users on `stable` to `win-x64`, while also creating a new channel named `win-arm64`. - -You should publish your next update (say v2.0.0) using `--channel win-x64`, which will create a new `releases.win-x64.json` file. You can now copy this file and rename it to `releases.stable.json` and deploy both files along with your v2.0.0 `.nupkg` to your update server. Any users on the "stable" channel will find the `releases.stable.json` file and update to your v2.0.0 win-x64 release, and once done will search for future updates at `releases.win-x64.json`. You only need to do this once, you will not need to update the `releases.stable.json` file again, however you may not want to delete it so users who have not opened your app in some time can still find the new updates. \ No newline at end of file diff --git a/docfx/docs/packaging/installer.md b/docfx/docs/packaging/installer.md deleted file mode 100644 index 297b69d2..00000000 --- a/docfx/docs/packaging/installer.md +++ /dev/null @@ -1,48 +0,0 @@ -*Applies to: Windows, MacOS* - -# Installer Overview -Velopack takes a relatively light-touch when it comes to installers, so there is not a lot of customisation available like you would find in other installation frameworks. This is the tradeoff Velopack makes to ensure that the developer/user experience is as fast and easy as possible. - -In both operating systems, if [code signing is configured](signing.md) the installer will also be signed. (This is _required_ on MacOS) - -## Windows Overview -The Windows installer is currently a "one-click" installer, meaning when the `Setup.exe` binary is run, Velopack will not show any questions / wizards to the user, it will simply attempt to install the app as fast as possible and then launch it. - -The setup will install a shortcut to `StartMenuRoot` and `Desktop` by default. [[Read more]](../updating/shortcuts.md) - -The key options which will customize the installer are as follows: -- `--packTitle {app name}` customizes shortcut names, the Apps & Features name, and the portable entry exe name. -- `--icon {path}` sets the .ico on Update.exe and Setup.exe (and also the icon of any dialogs shown) -- `--splashImage {path}` sets the (possibly animated) splash image to be shown while installing. - -The splash image can be a `jpeg`, `png`, or `gif`. In the latter case, it will be animated. - -You can also [bootstrap required frameworks](bootstrapping.md) before installing your app. - -The Windows installer will extract the application to `%LocalAppData%\{packId}`, and the directory structure will look like: - -``` -{packId} -├── current -│ ├── YourFile.dll -│ ├── sq.version -│ └── YourApp.exe -└── Update.exe -``` - -The `current` directory will be fully replaced [while doing updates](../updating/overview.md). The other two files added by Velopack (`Update.exe` and `sq.version`) are crucial and are required files for Velopack to be able to properly update your application. - -## MacOS Overview -The MacOS installer will be a standard `.pkg` - which is just a bundle where the UI is provided by the operating system, allowing the user to pick the install location. The app will be launched automatically after the install (mirroring the behavior on Windows) because of a `postinstall` script added by Velopack. - -The key options which will customize the installer are as follows: -- `--packTitle {app name}` customizes the name of the `.app` bundle and the app name shown in the `.pkg` -- `--pkgWelcome {path}` adds a Welcome page -- `--pkgReadme {path}` adds a Readme page -- `--pkgLicense {path}` adds a License Acceptance page -- `--pkgConclusion {path}` adds a Conclusion page -- `--noPkg` disable generating a `.pkg` installer entirely - -The pkgPage arguments can be a `.rtf` or a `.html` file. - -The `.app` package can be extracted to `/Applications` or `~/Applications`, this is selected by the user while installing. \ No newline at end of file diff --git a/docfx/docs/packaging/overview.md b/docfx/docs/packaging/overview.md deleted file mode 100644 index 158c266e..00000000 --- a/docfx/docs/packaging/overview.md +++ /dev/null @@ -1,58 +0,0 @@ -*Applies to: Windows, MacOS, Linux* -# Packaging Overview - -Packaging a release is accomplished with the `pack` command in Velopack. Regardless of your operating system, the common required arguments are roughly the same. - -## Creating your first release -You first should compile your application with whatever toolchain you would normally use (eg. `dotnet publish`, `msbuild.exe`, so forth). -Henceforth this will be called `{build_dir}`. - -### Required arguments -- `--packId {id}` The unique ID of your application. This should be unique enough to avoid other application authors from colliding with your app. -- `--packVersion {version}` The current version you are releasing - in [semver2 format](https://semver.org/) (eg. `1.0.0-build.23+metadata`). -- `--packDir {build_dir}` The folder containing your compiled application. -- `--mainExe {exeName}` The main executable to be started after install, and the binary that will [handle Velopack Hooks](../updating/overview.md). -- `--icon {path}` The icon used to bundle your app. Only required on MacOS and Linux. - -> [!TIP] -> Velopack does not support 4 part versions (eg. `1.0.0.0`), as it would not be practical to support both formats simultaneously and semver2 offers a lot more flexibility. - -A complete example: -```cmd -dotnet publish -c Release -r win-x64 -o publish -vpk pack --packId MyAppId -packVersion 1.0.0 --packDir publish --mainExe MyApp.exe -``` - -### Optional recommended arguments -There are many optional arguments, the best way to see what features are available for your operating system is to check `vpk pack -h`. To mention a couple: -- `--packTitle {name}` The friendly name for your app, shown to users in dialogs, shortcuts, etc. -- `--outputDir {path}` The location Velopack should create the final releases (defaults to `.\Releases`) - -### Release output -When building a release has completed, you should have the following assets in your `--outputDir`: -- `MyAppId-1.0.0-full.nupkg` - Full Release: contains your entire update package. -- `MyAppId-1.0.0-delta.nupkg` - Delta Release: only if there was a previous release to build a delta from. These are optional to build/deploy, but speeds up the updating process for sers because they only need to download what's changed between versions instead of the full package. -- `MyAppId-Portable.zip` - Portable Release: Can deploy this optionally to allow users to run and update your app without installing. -- `MyAppId-Setup.exe` - Installer: Used by most users to install the app to the local filesystem. -- `releases.{channel}.json` - Releases Index: a list of every available release. Used by `UpdateManager` to locate the latest applicable release. -- `RELEASES` - Legacy Releases File: only used for clients [migrating to Velopack](../migrating.md) from Squirrel. -- `assets.{channel}.json` - Build Assets: A list of assets created in the most recent build. Used by [Velopack deployment commands](../distributing/overview.md). - -You do not need to deploy all of these files to allow users to update, so you should review the [deployment guide](../distributing/overview.md) for more information on which files to distribute. - -> [!TIP] -> There is no setup/installer package for Linux. The program is distributed as a self-updating `.AppImage`. The reason is that `.AppImage` will run on pretty much every modern distro with no extra dependencies needed. Just download the `.AppImage`, run `chmod +x`, and click it to start. It is possible to install an `.AppImage`, but this is left up to the user to install something like [appimaged](https://github.com/probonopd/go-appimage/blob/master/src/appimaged/README.md) or [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher). - -## Code signing -While this is not required for local builds / testing, you should always code-sign your application before distributing your application to users. - -> [!WARNING] -> If you do not code-sign, your application may fail to run. [[Read more]](signing.md) - -## Customising the installer -On platforms which ship installers, you can customise the behavior. [[Read more]](installer.md) - -## Other recommended arguments -- If your application is operating-system or CPU architecture specific you should consider adding an `--rid`. [[Read more]](rid.md) -- If you plan on distributing release channels for different architectures or features, consider adding a `--channel` [[Read more]](channels.md) -- If your app requires additional frameworks (eg. vcredist) consider `--framework` [[Read more]](bootstrapping.md) \ No newline at end of file diff --git a/docfx/docs/packaging/rid.md b/docfx/docs/packaging/rid.md deleted file mode 100644 index 15da485a..00000000 --- a/docfx/docs/packaging/rid.md +++ /dev/null @@ -1,22 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# RID (Runtime Identifier) -Similar to how you provide a RID to dotnet to designate your target operating system and architecture, you can do the same for Velopack to tell it what your application supports. - -An RID is composed of three parts (`{os}{version?}-{arch}`) - - os: operating system (`win`, `osx`, or `linux`) - - version: optionally, specify minimum supported version (eg. `win7`, `win8.1`, `win10.0.18362`) - - arch: optionaly, specify supported CPU architecture (eg.`win-x86`, `win-x64`, `win-arm64`) - -If you were to provide the RID `--rid win10-arm64`, any users trying to install your app on Windows 7, 8, or 8.1 will receive a message saying their operating system is not supported. Similarly, if a Windows 11 user with an x64 cpu were trying to install - it would also fail with a helpful message. - -If trying to target Windows 11, they did not increment the major build number from 10 to 11. Anything >= build 22000 is classified as Windows 11. For example: - - `win11 == win10.0.22000` - - `win11.0.22621 == win10.0.22621` - -On MacOS, the RID (min version and arch) is just stored as metadata in the `.pkg` which will be handled natively by the operating system. - -#### Also read -- [Windows 10 version history](https://en.wikipedia.org/wiki/Windows_10_version_history) -- [Windows 11 version history](https://en.wikipedia.org/wiki/Windows_11_version_history) -- [.NET RID Catalog](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog) diff --git a/docfx/docs/packaging/signing.md b/docfx/docs/packaging/signing.md deleted file mode 100644 index 42fbc5d0..00000000 --- a/docfx/docs/packaging/signing.md +++ /dev/null @@ -1,173 +0,0 @@ -*Applies to: Windows, MacOS* - -# Code Signing -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 - -Here is the general rule of thumb for Windows Defender/Smart Screen warnings: -- You don't sign your code. You release MyApp-v1.exe. People get smart screen warnings for a while until the reputation on that file increases. You release MyApp-v2.exe. People get warnings again until MyApp-v2.exe builds up enough reputation. -- You sign your code with an OV certificate. You release MyApp-v1.exe. People get smart screen warnings for a while until the reputation on that certificate increases. You release MyApp-v2.exe. People don't get warnings because the certificate already has a good reputation. Eventually your certificate expires and it comes time to release MyApp-v47.exe. You renew your certificate, and people get warnings again until the new certificate builds up reputation. -- You sign your code with an EV certificate. People never get warnings. - -### Acquiring a code signing certificate -First, you need to acquire a code-signing certificate from a reputable brand. Microsoft lists the following trusted issuers [in their documentation](https://learn.microsoft.com/en-us/windows-hardware/drivers/dashboard/code-signing-cert-manage): - -- [Certum](https://shop.certum.eu/data-safety/code-signing-certificates/certum-ev-code-sigining.html) -- [SSL.com](https://www.ssl.com/certificates/ev-code-signing/) -- [DigiCert](https://www.digicert.com/signing/code-signing-certificates) -- [Entrust](https://www.entrustdatacard.com/products/digital-signing-certificates/code-signing-certificates) -- [GlobalSign](https://go.microsoft.com/fwlink/p/?LinkId=620888) -- [IdenTrust](https://www.identrust.com/digital-certificates/trustid-ev-code-signing) -- [Sectigo (formerly Comodo)](https://sectigo.com/ssl-certificates-tls/code-signing) - -> [!TIP] -> Note that since June 1, 2023 there [has been a policy change](https://knowledge.digicert.com/general-information/new-private-key-storage-requirement-for-standard-code-signing-certificates-november-2022), meaning it is no longer possible to directly download your code signing certificate private key as a file from issuers. This means most signing options available today will require you to participate in Cloud Code Signing, or install your certificate to a HSM (usb / hardware module). Some issurs may allow you to install your cert to a pre-owned/generic HSM, and some may force you to purchase and ship their own brand of HSM. CI/CD may not be possible with some issuers unless they provide tools specifically designed to do that. - -It may be possible to get official certificates from an authorised reseller at a cheaper price: -- [SignMyCode](https://signmycode.com/) -- [GoGetSSL](https://www.gogetssl.com/code-signing-ssl/) - -If looking for a cheap option, at the time of writing Certum does an [Open Source Cloud Signing Certificate](https://certum.store/data-safety/code-signing-certificates.html?as_dane_w_certyfikacie=5720) for $58. Note that it is not possible to automate Certum certificates with CI/CD because they require you to install virtual signing drivers (SimpleSign Desktop) and sign in to it with their 2FA SimplySign app. - -> [!WARNING] -> This document is by no means a recommendation or advice to purchase from any particular code-signing certificate issuer. This is just general guidance for the process one might follow to purchase a certificate, and you must validate for yourself that the issuer you choose is fit for your use-case. - -### Signing via `signtool.exe` -Usually signing is accomplished via `signtool.exe`. If you already use this tool to sign your application, you can just pass your sign parameters straight to Velopack (minus the 'sign' command). - -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. - -If you are using a USB / HSM and have the following signing error `Error: SignerSign() failed." (-2147023673/0x800704c7)`, this means that you are missing a password / unlock token. This can be added to your signing command with the `/csp /k` parameters. [[Read more]](https://stackoverflow.com/questions/17927895/automate-extended-validation-ev-code-signing-with-safenet-etoken/54439759#54439759) - -> [!WARNING] -> Take care when providing parameters with spaces. You must wrap anything containing spaces with quotes and escape with a backslash. For example, `--signParams "/n \"My Cert Name\""`. If you are using an MSBuild `` task or similar, you will need to use `"` instead. - -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. - -### Creating code signing certificates -1. First, you will need to create an account at https://developer.apple.com, pay the annual developer fee, and accept any license agreements. -0. Navigate to your certificates: https://developer.apple.com/account/resources/certificates -0. Click the (+) icon to create new certificates. You need to create both a `Developer ID Installer` and a `Developer ID Application` certificate for distribution of Velopack apps outside the Mac App Store. ![apple certificate list](~/images/apple_certificate_list.png) -0. Open both certificates by clicking on them, press Download, and then double click the ".cer" file to install it to your local keychain. - -### Setting up a NotaryTool profile -1. Create an app-specific password: https://support.apple.com/en-us/102654. You will only be shown this password once, so save or write it down somewhere. -0. Find your apple team ID: https://developer.apple.com/account#MembershipDetailsCard -0. Store your Apple account credentials to a new NotaryTool profile: - ```sh - xcrun notarytool store-credentials \ - --apple-id "yourapple@account.com" \ - --team-id "your-located-team-id" \ - --password "your-generated-app-specific-password" \ - "your-local-profile-name-here" - ``` - -### Putting it all together -Now that you have your NotaryTool profile and code signing certificates installed, you can add the following parameters to your `pack` command: - -```sh -vpk pack \ - ... - --signAppIdentity "Developer ID Application: Your Name" \ - --signInstallIdentity "Developer ID Installer: Your Name" \ - --notaryProfile "your-local-profile-name-here" \ -``` - -When these parameters are specified and valid, Velopack will automatically code sign and notarize your application and installer packages. - -### Automate signing in CI/CD (Github Actions) -It is also posible to store your certificates and notary credentials as Action Secrets and sign your code during CI builds. - -1. Launch Keychain Access and open the "My Certificates" pane. -0. Select both certificates, right click and select "Export". Save as a p12 file and make note of the password. You can use the same password for both certificates. -0. Copy the contents of the certificate to clipboard as base64, example: - ```sh - base64 -i CERT.p12 | pbcopy - ``` -0. Create 7 [Github Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) for your Actions workflows - - `BUILD_CERTIFICATE_BASE64` (b64 of your app cert) - - `INSTALLER_CERTIFICATE_BASE64` (b64 of your installer cert) - - `P12_PASSWORD` (password for the certificates) - - `APPLE_ID` (your apple username) - - `APPLE_PASSWORD` (your app-specific password from earlier) - - `APPLE_TEAM` (your team id from earlier) - - `KEYCHAIN_PASSWORD` (can be any random string, will be used to create a new keychain) - -0. Add a step to your workflow which installs the certificates and keychain profile. Here is an example: - ```yml - name: App build & sign - on: push - jobs: - build_with_signing: - runs-on: macos-latest - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Install Apple certificates and notary profile - env: - BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }} - INSTALLER_CERTIFICATE_BASE64: ${{ secrets.INSTALLER_CERTIFICATE_BASE64 }} - P12_PASSWORD: ${{ secrets.P12_PASSWORD }} - APPLE_ID: ${{ secrets.APPLE_ID }} - APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }} - APPLE_TEAM: ${{ secrets.APPLE_TEAM }} - KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }} - run: | - # create variables for file paths - CERT_BUILD_PATH=$RUNNER_TEMP/build_certificate.p12 - CERT_INSTALLER_PATH=$RUNNER_TEMP/installer_certificate.p12 - KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db - - # import certificates from secrets - echo -n "$BUILD_CERTIFICATE_BASE64" | base64 --decode -o $CERT_BUILD_PATH - echo -n "$INSTALLER_CERTIFICATE_BASE64" | base64 --decode -o $CERT_INSTALLER_PATH - - # create temporary keychain - security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH - security set-keychain-settings -lut 21600 $KEYCHAIN_PATH - security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH - - # import certificates to keychain - security import $CERT_BUILD_PATH -P "$P12_PASSWORD" -A -t cert -f pkcs12 -k $KEYCHAIN_PATH - security import $CERT_INSTALLER_PATH -P "$P12_PASSWORD" -A -t cert -f pkcs12 -k $KEYCHAIN_PATH - security list-keychain -d user -s $KEYCHAIN_PATH - - # create notarytool profile - xcrun notarytool store-credentials --apple-id "$APPLE_ID" --team-id "$APPLE_TEAM" --password "$APPLE_PASSWORD" velopack-profile - - - name: Build app - ... - - - name: Create Velopack Release - run: | - dotnet tool install -g vpk - vpk ... --signAppIdentity "Developer ID Application: Your Name" --signInstallIdentity "Developer ID Installer: Your Name" --notaryProfile "velopack-profile" - - - name: Clean up keychain - if: ${{ always() }} - run: security delete-keychain $RUNNER_TEMP/app-signing.keychain-db - ``` \ No newline at end of file diff --git a/docfx/docs/packaging/toc.yml b/docfx/docs/packaging/toc.yml deleted file mode 100644 index 28128874..00000000 --- a/docfx/docs/packaging/toc.yml +++ /dev/null @@ -1,12 +0,0 @@ -- name: Overview - href: overview.md -- name: Release Channels - href: channels.md -- name: Code Signing - href: signing.md -- name: Installer Overview - href: installer.md -- name: Boostrapping (.NET, .Net Framework, VCRedist, etc) - href: bootstrapping.md -- name: RID / Min Supported OS - href: rid.md \ No newline at end of file diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml deleted file mode 100644 index 18a22b5d..00000000 --- a/docfx/docs/toc.yml +++ /dev/null @@ -1,53 +0,0 @@ - -- name: Get started - -- name: Welcome - href: index.md - -- name: Quick - C# .NET - href: getting-started/csharp.md - -- name: Quick - Rust - href: getting-started/rust.md - -- name: Quick - JS & Electron - href: getting-started/electron.md - -- name: Sample Apps - items: - - name: C# Avalonia / Cross Platform - href: https://github.com/velopack/velopack/tree/master/samples/AvaloniaCrossPlat - - name: C# WPF / .Net Framework - href: https://github.com/velopack/velopack/tree/master/samples/VeloWpfSample - - name: C++ / MSVC / Win32 - href: https://github.com/velopack/velopack.fusion/tree/master/for-cpp/samples/win32 - - name: Rust / iced-rs - href: https://github.com/velopack/velopack.fusion/tree/master/for-rust/samples/iced - - name: JS / Electron - href: https://github.com/velopack/velopack.fusion/tree/master/for-js/samples/electron-forge - -- name: Essentials - -- name: App Updating - href: updating/toc.yml - homepage: updating/overview.md - -- name: Packaging Releases - href: packaging/toc.yml - homepage: packaging/overview.md - -- name: Distributing Releases - href: distributing/toc.yml - homepage: distributing/overview.md - -- name: Advanced - -- name: Troubleshooting - href: troubleshooting/toc.yml - homepage: troubleshooting/debugging.md - -- name: Migrating to Velopack - href: migrating.md - -- name: Contributing - href: compiling.md \ No newline at end of file diff --git a/docfx/docs/troubleshooting/cli.md b/docfx/docs/troubleshooting/cli.md deleted file mode 100644 index facb8a4d..00000000 --- a/docfx/docs/troubleshooting/cli.md +++ /dev/null @@ -1,87 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Velopack Command Line Reference - -## vpk -```txt -Description: - Velopack CLI 0.0.61-g2e7ffeb (prerelease) for creating and distributing releases. - -Usage: - vpk [command] [options] - -Options: - -?, -h, --help Show help and usage information - --version Show version information - --verbose Print diagnostic messages. - -Commands: - pack Creates a release from a folder containing application files. - download Download's the latest release from a remote update source. - upload Upload local package(s) to a remote update source. - delta Utilities for creating or applying delta packages. -``` - -## Update.exe & UpdateMac -```txt -Velopack Updater (0.0.66) manages packages and installs updates. -https://github.com/velopack/velopack - -Usage: update [OPTIONS] - update apply [OPTIONS] [-- [EXE_ARGS]...] - update patch [OPTIONS] --old --patch --output - update start [OPTIONS] [EXE_NAME] [-- [EXE_ARGS]...] - update uninstall [OPTIONS] - -Options: - --verbose Print debug messages to console / log - -s, --silent Don't show any prompts / dialogs - -l, --log Override the default log file location - -h, --help Print help - -V, --version Print version - -update apply: -Applies a staged / prepared update, installing prerequisite runtimes if necessary - -r, --restart Restart the application after the update - -w, --wait Wait for the parent process to terminate before applying the update - -p, --package Update package to apply - --noelevate If the application does not have sufficient privileges, do not elevate to admin - -h, --help Print help - [EXE_ARGS]... Arguments to pass to the started executable. Must be preceeded by '--'. - -update patch: -Applies a Zstd patch file - --old Base / old file to apply the patch to - --patch The Zstd patch to apply to the old file - --output The file to create with the patch applied - -h, --help Print help - -update start: -Starts the currently installed version of the application - -w, --wait Wait for the parent process to terminate before starting the application - -h, --help Print help - [EXE_ARGS]... Arguments to pass to the started executable. Must be preceeded by '--'. - [EXE_NAME] The optional name of the binary to execute - -update uninstall: -Remove all app shortcuts, files, and registry entries. - -h, --help Print help -``` - - -## Setup.exe - -```txt -Velopack Setup (0.0.66) installs applications. -https://github.com/velopack/velopack - -Usage: setup [OPTIONS] - -Options: - -s, --silent Hides all dialogs and answers 'yes' to all prompts - -v, --verbose Print debug messages to console - -l, --log Enable file logging and set location - -t, --installto Installation directory to install the application - -d, --debug Debug mode, install from a nupkg file - -h, --help Print help -``` \ No newline at end of file diff --git a/docfx/docs/troubleshooting/debugging.md b/docfx/docs/troubleshooting/debugging.md deleted file mode 100644 index d014cf1e..00000000 --- a/docfx/docs/troubleshooting/debugging.md +++ /dev/null @@ -1,41 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Debugging Velopack - -## Logging -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.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 -using Microsoft.Extensions.Logging; - -// ... - -class ConsoleLogger : ILogger -{ - public IDisposable BeginScope(TState state) where TState : notnull => null; - public bool IsEnabled(LogLevel logLevel) => true; - public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, Func formatter) - => Console.WriteLine(formatter(state, exception)); -} - -// ... - -new UpdateManager("https://path.to/your-updates", logger: new ConsoleLogger()); -``` - -### Windows -Running Update.exe will log most output to it's base directory as `Velopack.log`. Setup.exe will not log to file by default. However, you can override the log location for both binaries with the `--log {path}` parameter. You can also use the `--verbose` flag to capture debug/trace output to log. Unfortunately, on Windows, to avoid showing up as a console window, these binaries are compiled as a WinExe and there will be no console output by default. Please see the [command line reference](cli.md) for a comprehensive list of arguments supported. - -### MacOS / Linux -All logs will be sent to `/tmp/velopack.log`. - -## Advanced Debugging -The debug builds of Velopack binaries have additional logging/debugging capabilities, and will produce console output. In some instances, it may be useful to [compile Velopack](../compiling.md) for your platform, and replace the release binaries of Setup.exe and Update.exe with debug versions. - -If your issue is with package building, after building the rust binaries in Debug mode, it can also be useful to run the Velopack.Vpk project from Visual Studio with your intended command line arguments rather than running the `vpk` tool directly. - -If doing this has not helped, you may need to debug and step through the rust binaries - for which I recommend the CodeLLDB VSCode extension. \ No newline at end of file diff --git a/docfx/docs/troubleshooting/toc.yml b/docfx/docs/troubleshooting/toc.yml deleted file mode 100644 index b33b6a19..00000000 --- a/docfx/docs/troubleshooting/toc.yml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Debugging / Logging - href: debugging.md -- name: Command Line Reference - href: cli.md \ No newline at end of file diff --git a/docfx/docs/updating/hooks.md b/docfx/docs/updating/hooks.md deleted file mode 100644 index ef9da995..00000000 --- a/docfx/docs/updating/hooks.md +++ /dev/null @@ -1,25 +0,0 @@ -*Applies to: Windows* - -# Hooks -In general, I don't recommend trying to handle hooks manually - and instead refer to the available [VelopackApp](/sdk/Velopack.VelopackApp.html) options. - -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 (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. -- `--veloapp-updated {version}` Runs on the new version of the app, after an update is applied. App must handle and exit within 15 seconds. -- `--veloapp-uninstall {version}` Runs before an uninstall takes place. App must handle and exit within 30 seconds. - -At this time, there is no way to provide feedback during the hooks that you would like to cancel the install/uninstall/update etc, and you may not show any UI to the user. - -> [!WARNING] -> If your application receives one of these arguments and does not exit within the alloted time, it will be killed. - -## Environment variable hooks -There are also two environment variables that get set, if these are detected your app does not need to exit. - -- `VELOPACK_FIRSTRUN` is true if this is the first run after the app was installed. -- `VELOPACK_RESTART` is true if the application was restarted by Velopack (usually because an update was applied.) \ No newline at end of file diff --git a/docfx/docs/updating/overview.md b/docfx/docs/updating/overview.md deleted file mode 100644 index b7d95503..00000000 --- a/docfx/docs/updating/overview.md +++ /dev/null @@ -1,106 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Updating Overview -To integrate Velopack into your application, you *must* initialise the Velopack as early as possible in app startup, and you *should* add update checking code somewhere. - -For .NET applications, you should first install the [Velopack Nuget Package](https://nuget.org/packages/velopack). - -## 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. This should be in the "main" binary (the one specified when packaging with `--mainExe {exeName}`). - -```cs -static void Main(string[] args) -{ - VelopackApp.Build().Run(); - // ... your other startup code below -} -``` - -There are a variety of options / callbacks you can specify here to customise Velopack, for example: - -```cs -static void Main(string[] args) -{ - ILogger log = CreateLogger(); - VelopackApp.Build() - .WithBeforeUninstallFastCallback((v) => { - // delete / clean up some files before uninstallation - }) - .WithFirstRun((v) => { - MessageBox.Show("Thanks for installing my application!"); - }) - .Run(log); -} -``` - -The full list of options [for VelopackApp is available here](/sdk/Velopack.VelopackApp.html). You can also read more about [how hooks work](hooks.md). - -> [!WARNING] -> A "FastCallback" requires that your application show no UI and exit quickly. When the callback returns, your application will exit. If you do not exit this callback quickly enough your process will be killed. - -## Configuring Updates -Updates can be accomplished by adding [UpdateManager](/sdk/Velopack.UpdateManager.html) to your app: - -```cs -private static async Task UpdateMyApp() -{ - var mgr = new UpdateManager("https://the.place/you-host/updates"); - - // check for new version - var newVersion = await mgr.CheckForUpdatesAsync(); - if (newVersion == null) - return; // no update available - - // download new version - await mgr.DownloadUpdatesAsync(newVersion); - - // install new version and restart app - mgr.ApplyUpdatesAndRestart(newVersion); -} -``` - -> [!TIP] -> Updates can be done silently in the background, or integrated into your application UI. It's always up to you. - -You can host your update packages basically anywhere, here are a few examples: -- Local directory:
`new UpdateManager("C:\Updates")` -- HTTP server, or S3, Azure Storage, etc:
`new UpdateManager("https://the.place/you-host/updates")` -- GitHub Releases:
`new UpdateManager(new GitHubSource("https://github.com/yourName/yourRepo")` - -There are a variety of [built-in sources](/sdk/Velopack.Sources.html) you can use when checking for updates, but you can also build your own by [deriving from IUpdateSource](/sdk/Velopack.Sources.IUpdateSource.html). - -### Check for updates -`CheckForUpdatesAsync` will read the provided update source for a `releases.{channel}.json` file to retrieve available updates ([Read about channels](../packaging/channels.md)). If there is an update available, a non-null [UpdateInfo](/sdk/Velopack.UpdateInfo.html) will be returned with some details about the update. You can also [retrieve any release notes](release-notes.md) which were provided when the update was packaged. - -There are [also some options](/sdk/Velopack.UpdateOptions.html) which can be passed in to [UpdateManager](/sdk/Velopack.UpdateManager.html) to customise how updates are handled, eg. to allow things like [switching channels](switching-channels.md). - -### Download updates -`DownloadUpdatesAsync` will attempt to download deltas (if available) and re-construct the latest full release. If there are no deltas available, or the delta reconstruction fails, the latest full release package will be downloaded instead. Note that if an option like `AllowVersionDowngrade` is specified, the downloaded version might be older than the currently executing version. - -### Apply updates -Once the update has downloaded, you have a few options available. Calling `ApplyUpdatesAndRestart` or `ApplyUpdatesAndExit` will exit your app, install any [bootstrap prerequisites](../packaging/bootstrapping.md), install the update, and then optionally restart your app right away. - -If you do not want to exit your app immediately, you can call `WaitExitThenApplyUpdates` instead, which will launch Update.exe and wait for 60 seconds before proceeding. If your app has not exited within 60 seconds it will be killed. - -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. - -## 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). \ No newline at end of file diff --git a/docfx/docs/updating/release-notes.md b/docfx/docs/updating/release-notes.md deleted file mode 100644 index 6da61676..00000000 --- a/docfx/docs/updating/release-notes.md +++ /dev/null @@ -1,23 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Release Notes -It is possible to store release notes (Markdown) in update packages and access it while Updating. This could be useful, for example, to show a user a list of changes before downloading a update. - -- Write your release notes to a file (eg. releasenotes.md). -- While packing your release, provide these to Velopack with `--releaseNotes {path/to/releasenotes.md}` - -The Velopack builder will render this to HTML for your convenience, and store both the HTML and the markdown into your update package. - -Now, release notes will be available while checking for updates, for example: - -```cs -private static async Task UpdateMyApp() -{ - var mgr = new UpdateManager("https://the.place/you-host/updates"); - - var newVersion = await mgr.CheckForUpdatesAsync(); - if (newVersion != null) { - new ReleaseNotesHtmlWindow(newVersion.TargetFullRelease.ReleaseNotesHtml).Show(); - } -} -``` \ No newline at end of file diff --git a/docfx/docs/updating/shortcuts.md b/docfx/docs/updating/shortcuts.md deleted file mode 100644 index 2777a05f..00000000 --- a/docfx/docs/updating/shortcuts.md +++ /dev/null @@ -1,19 +0,0 @@ -*Applies to: Windows* - -# Windows Shortcuts -By default, during installation Velopack will create a shortcut on the Desktop and in the StartMenuRoot. It will automatically delete any shortcuts it finds when uninstalling the application. - -The name of the shortcuts will be determined by the `--packTitle` vpk argument. For example, if you pass `--packTitle "My Fancy App"`, then the shortcuts created will be created as `"My Fancy App.lnk"`. - -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. - -For example, if you wished to create a shortcut during the install of your app, you might do the following: - -```cs -using Velopack; -using Velopack.Windows; - -VelopackApp.Build() - .WithAfterInstallFastCallback((v) => new Shortcuts().CreateShortcutForThisExe(ShortcutLocation.Desktop)) - .Run() -``` \ No newline at end of file diff --git a/docfx/docs/updating/switching-channels.md b/docfx/docs/updating/switching-channels.md deleted file mode 100644 index 8a3679a8..00000000 --- a/docfx/docs/updating/switching-channels.md +++ /dev/null @@ -1,28 +0,0 @@ -*Applies to: Windows, MacOS, Linux* - -# Switching Channels -By default, `UpdateManager` will try and search for releases in the same channel that it was built for. You can [read more about packaging channels here](../packaging/channels.md). So normally, you should not provide a channel at all to the `UpdateManager` constructor. - -However, from time to time, it may be useful to allow a user to switch channels without re-installing the application. For example, a user opts into getting "beta" features via your application settings. In that case, you can provide the channel explicitly: - -```cs -new UpdateManager("https://the.place/you-host/updates", new UpdateOptions { ExplicitChannel = "beta" }); -``` - -Also by default, the UpdateManager will only update to versions which are newer than the current version, leading to suboptimal behavior because often you may be switching to a version which is lower than the current version. Imagine the following scenario: - -- You publish 2.0.0 to the `stable` channel. -- You publish 2.0.1 through 2.0.5 to the `beta` channel. -- Your user installs 2.0.0 `stable`, and then opts-in to `beta` via settings. -- Your user can update from 2.0.0 -> 2.0.5 fine, because 2.0.5 is a newer version. -- Your user encounters a bug and turns off `beta` via settings. -- By default, UpdateManager will not install stable 2.0.0 because it is a lower version than 2.0.5. - -It's for this reason I recommend always using the `ExplicitChannel` option with the `AllowVersionDowngrade` option. For example: - -```cs -new UpdateManager("https://the.place/you-host/updates", new UpdateOptions { - ExplicitChannel = "beta", - AllowVersionDowngrade = true, -}); -``` diff --git a/docfx/docs/updating/toc.yml b/docfx/docs/updating/toc.yml deleted file mode 100644 index 76f4c687..00000000 --- a/docfx/docs/updating/toc.yml +++ /dev/null @@ -1,10 +0,0 @@ -- name: Overview - href: overview.md -- name: Windows Shortcuts - href: shortcuts.md -- name: Release Notes - href: release-notes.md -- name: Switching Channels - href: switching-channels.md -- name: Handling Hooks - href: hooks.md \ No newline at end of file diff --git a/docfx/images/Velopack_200.png b/docfx/images/Velopack_200.png deleted file mode 100644 index c278b606..00000000 Binary files a/docfx/images/Velopack_200.png and /dev/null differ diff --git a/docfx/images/apple_certificate_list.png b/docfx/images/apple_certificate_list.png deleted file mode 100644 index 8ef6357f..00000000 Binary files a/docfx/images/apple_certificate_list.png and /dev/null differ diff --git a/docfx/images/velopack-black.svg b/docfx/images/velopack-black.svg deleted file mode 100644 index cc75f717..00000000 --- a/docfx/images/velopack-black.svg +++ /dev/null @@ -1,37 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docfx/images/velopack-white.svg b/docfx/images/velopack-white.svg deleted file mode 100644 index 6431d079..00000000 --- a/docfx/images/velopack-white.svg +++ /dev/null @@ -1,37 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/src/Velopack/Sources/IUpdateSource.cs b/src/Velopack/Sources/IUpdateSource.cs index e255b6ae..9c1674c2 100644 --- a/src/Velopack/Sources/IUpdateSource.cs +++ b/src/Velopack/Sources/IUpdateSource.cs @@ -31,7 +31,7 @@ namespace Velopack.Sources Task GetReleaseFeed(ILogger logger, string channel, Guid? stagingId = null, VelopackAsset? latestLocalRelease = null); /// - /// Download the specified to the provided local file path. + /// Download the specified to the provided local file path. /// /// The release to download. /// The path on the local disk to store the file. If this file exists,