Package, version and sign

Pack an activity package, version it, keep it compatible with the Studios and Robots you support, and sign it.

Pack# PowerShellCopydotnet pack Contoso.Invoices -c Release -o out dotnet pack builds the runtime project, stages the package layout and runs the packaging build from VeloPhex.ActivityPackage.Build, which: Checks that the package states a licence (VXMAN010, VXMAN011) and that the release notes start with the version being packed (VXMAN012, VXMAN013). Stages lib/, design/ (if you have a design project), icons/, resources/, README.md and the licence file. Reads your activities' metadata and checks them: at least one activity (VXMAN002), a package icon (VXMAN007), an icon for every icon key (VXMAN008), icon size and format, no reserved argument names (VXPKG051), and every design rule (VXDSN codes). Writes velophex/activity-manifest.json and velophex/activity-design.json, with a hash of every file. Prints one summary line, info VXDSN000: N activities, M card properties, K conditions, W warnings, and creates the .nupkg. Every check that fails stops the pack with the code, the activity concerned and the fix. See Build diagnostics. Do not change a package after it is packedAny file added to or changed in the .nupkg after the build makes it invalid (VXPKG023, VXPKG024), and Studio and Robots refuse it. A detached signature is the only thing that may be added. To change anything, change the source and pack again. Versions# Set the version in Directory.Build.props: Directory.Build.propsXMLCopy<Version>1.2.0-preview.1</Version> and lead the release notes in the package project with it: Contoso.Invoices.Activities.Package.csprojXMLCopy<PackageReleaseNotes>$(Version): Adds Get Invoice Status.</PackageReleaseNotes> Rules: A published version never changes. Every project that installs your package pins its exact bytes by hash in project.lock.json, and Studio caches a package's design metadata per id and version. A repacked version with the same number either fails the hash check or keeps showing the old metadata. Every change, however small, gets a new version. Use prerelease versions while you build on prerelease SDK packages. A stable package cannot depend on a prerelease Velophex.Workflow.Sdk (NuGet NU5104); the template starts at 1.0.0-preview.1 for that reason. Version by semantic versioning. Adding an activity or an optional argument is a minor change. Removing or renaming an activity or argument breaks saved workflows; do it by adding a new activity with a new type id and hiding the old one ([ActivityInfo(Hidden = true)]). Engine compatibility# Every package declares the range of workflow engine versions it runs on, engineVersionRange in its manifest. It comes from VelophexEngineVersionRange in VeloPhex.Versions.props and has the form [<engine you built against>, 1.0.0). Your package also depends on Velophex.Workflow.Sdk at that same version. What that means for the people who use your package: Situation Result Studio or Robot engine is at or above your package's floor The package installs and runs Studio or Robot engine is older than your floor The package is refused (VXPKG016). In Studio its activities do not appear, and a package already in the project shows as Could not be loaded under Dependencies. On a Robot the job fails. A project uses several activity packages whose ranges cannot all be met by one engine The automation package is not built (VXPKG054); the message names each package's range You built against a newer Velophex.Studio.Sdk than the Studio that loads your design assembly Studio skips your design assembly and says why in the Output panel, naming both versions; the activities still show without your custom editors and data providers VeloPhex supports packages built against the current SDK release and the one before it. Guidelines: Build against the oldest SDK release that has what you need. Your floor is the version you build against, so building against the newest SDK excludes Studios and Robots that have not been upgraded yet. Move the four lines of VeloPhex.Versions.props together, to the values of one release, by installing that release's template or copying its file. A build tool and SDK from different releases fail the pack (VXDSN001, VXDSN017). Never lower the floor by hand. The engine's manifest reader refuses members it does not know, so an older engine would reject your manifest anyway. When you raise the floor, tell your users which Studio and Robot versions they need, and give the package a new minor or major version. Licence# Every package must state a licence. Replace the template's LICENSE.txt with yours; the package project already packs it: Contoso.Invoices.Activities.Package.csprojXMLCopy<PackageLicenseFile>LICENSE.txt</PackageLicenseFile> <VeloPhexLicenseSource>$(MSBuildProjectDirectory)\LICENSE.txt</VeloPhexLicenseSource> Or use an SPDX expression instead, for example <PackageLicenseExpression>MIT</PackageLicenseExpression>, and remove the two lines above. Keep the licences and notices of any third-party libraries you depend on. Sign# VeloPhex.ActivityPackage.Build does not sign packages, and a package does not need a signature to install and run. Signing decides how much Studio and your Robots trust it: Studio installs an unsigned package after the author consents, and warns explicitly when an unsigned package asks for the UiAutomation or Credentials capability. It runs a package's design assembly only if the package is signed by a pinned signer or comes from a package source marked Trusted. Without either, your activities still work and are presented from their design document. Robots and the Orchestrator can be configured to require signed packages and to trust your organization's signer by its certificate pin. A signature that is present is always verified, and a broken one is always refused. If your organization signs packages, sign each version once, before you distribute it: signing changes the package hash that every project lock file pins. See Signing packages for the signature format, pinning a signer on Studio, Robots and the Orchestrator, and certificate rotation, and Package signing and supply chain for the trust rules. Next steps# Publish and install

Pack

Versions

Engine compatibility

Licence

Sign

Next steps