Upgrading to BuildMaster 6.1
This document is only for users of BuildMaster v5 or v6.0; if you’re using using v3 or v4, please follow KB#1151 Upgrading from BuildMaster v3 and v4 for upgrade options
Change Summary
The following table summarizes all of the changes introduced in v6.0 and v6.1, and the details can be found below.
If you’re upgrading from v5, please note that all custom extensions must be recompiled and you will need to take care in upgrading extensions
BuildMaster 6.0 |
|
BuildMaster 6.1 |
|
Upgrade Process
You can only upgrade from BuildMaster v5 or BuildMaster v6.1. To upgrade from one of these versions:
- Download and run the Inedo Hub from my.inedo.com/downloads or use the latest traditional installer
-
Remove old (5.x) extensions as appropriate
-
Reasons you may need to remove extensions:
- If the extension shows an error message, stating it failed to load for any reason. Remove it and reinstall {ExtensionName}Legacy or {ExtensionName}.
- If the extension shows a higher installed version than the available version. Remove it and reinstall {ExtensionName}Legacy or {ExtensionName}.
- See upgrading extensions for more information.
-
Reasons you may need to remove extensions:
- Install the 6.1 extensions
Risk Mitigation
Although the risks vary depending on which version you’re upgrading from, you should take the following precautions to prevent downtime:
- Make sure that your BuildMaster database is backed up prior to upgrade
- Make sure that your Encryption Key is backed up prior to upgrade
- Make sure that the installation’s \Extensions directory is backed up prior to upgrade
Rollback
Because there are database changes, a rollback will require uninstalling BuildMaster, and then restoring your BuildMaster instance.
Upgrading Extensions
Extensions in BuildMaster v6 can now be compiled against the Inedo.SDK. This also means that existing extensions need to be recompiled against the Inedo.BuildMaster.SDK 6.0, or if no legacy features are used, the latest Inedo.SDK package from NuGet. If the intent is to upgrade to v6.2, the Inedo.SDK must be referenced as the Inedo.BuildMaster.SDK will be removed.
Because of this, customers that still use any legacy plans, build importers, source control providers, or issue tracking providers must download the {ExtensionName}Legacy extension in addition to the {ExtensionName} extension counterpart . The complete list of available legacy extensions is here:
- TFSLegacy
- JiraLegacy
- TeamCityLegacy
- MercurialLegacy
- JenkinsLegacy
- FTPLegacy
- AzureLegacy
- AmazonLegacy
- YouTrackLegacy
- NuGetLegacy
- WindowsLegacy
- InedoCoreLegacy
Any {ExtensionName}Legacy extensions will be removed in v6.2.
Which NuGet package should I choose?
Extensions that implement any legacy features (e.g. legacy plan actions, source control providers, issue tracker connections, database connections)
must use v6 of the Inedo.BuildMaster.SDK. Database calls (i.e. DB.
) or references to strongly-typed tables names (i.e. Tables.
)
are also not available in the Inedo.SDK since it is shared across multiple products. Support for shared/common objects (e.g. servers, roles) is supported via the
SDK
class.
If no legacy features are used and there is no reliance on specific database calls, the extension should use the latest Inedo.SDK NuGet package. The complete list of Inedo.SDK supported classes can be found in the Inedo SDK Reference.
Upgrading Extensions
Upgrading a pre-v6 extension (whether using the Inedo.BuildMaster.SDK or Inedo.SDK) requires the following:
- Target framework must be set to .NET 4.5.2 at a minimum
- For Inedo.BuildMaster.SDK: Upgrade the SDK NuGet package to v6.0.0 (this will also install Inedo.SDK as a dependency)
- For Inedo.BuildMaster.SDK or Inedo.SDK: Upgrade the Inedo.SDK to the latest version
-
NuGet will automatically reference the following packages, ensure they are set to CopyLocal=false and SpecificVersion=false in the project properties:
BuildMaster.Web.Controls
(Inedo.BuildMaster.SDK only)BuildMasterCore
(Inedo.BuildMaster.SDK only)Inedo.Agents.Client
Inedo.ExecutionEngine
Inedo.SDK
InedoLib
-
To resolve most compiler errors that you will receive on NuGet package upgrade, the ALT+SHIFT+F10 keyboard shortcut
that brings up the Light Bulb will quickly apply the appropriate
using
statements
Class & Namespace Changes
-
PromotionContext
no longer implementsIGenericBuildMasterContext
. While never documented as doing so, explicit casts to this interface must be removed -
All helper classes marked with
System.ObsoleteAttribute
in the pre-v6 SDK have been removed in v6. Most replacements toInedoLib.
Util.
are found inInedoLib.
AH
-
ILogger.Log()
extensions (e.g.LogDebug
,LogError
) accepted a format string in v4.X which was deprecated in v5.0, and now removed in v6.0; usestring
.Format()
inside theLog()
call instead
Pre-v6 Type Name | v6 Replacement |
---|---|
PromotionRequirementBase |
Inedo.Extensibility.PromotionRequirements. PromotionRequirement |
PromotionRequirementEditorBase |
Inedo.Extensibility.PromotionRequirements. PromotionRequirementEditor |
DeprecatedInBuildMasterVersionAttribute |
System. ObsoleteAttribute |
Util. Agents |
Use context.GetAgent() instead |
Util. Artifacts |
Use Artifact class |
SourceControlFileFolderPicker |
Inedo.Web. ScmBrowserTextBox or Inedo.Web. FileBrowserTextBox |
Inedo.BuildMaster. OtterScriptSymbolComparer |
Inedo.ExecutionEngine. OtterScriptSymbolComparer |
Inedo.BuildMaster.Mapping. ICustomArgumentMapper |
Inedo.ExecutionEngine.Mapping. ICustomArgumentMapper |
Inedo.BuildMaster.IssueTrackerConnections. IssueSources |
Inedo.Extensibility. IssueSources |
Inedo.BuildMaster.IssueTrackerConnections. IIssueTrackerIssue |
Inedo.Extensibility. IIssueTrackerIssue |
SuggestibleValue |
Inedo.Web. SuggestableValue (note the spelling change) |
InedoLib.Util.WriteJson( |
Newtonsoft.Json.JsonSerializer.CreateDefault().Serialize( |
Legacy SDK Change in BuildMaster 6.1
There is 1 possible breaking change between v6.0 and v6.1 of the BuildMaster SDK: ExecutionsFailedEvent
was renamed to ExecutionFailedEvent
. In the unlikely event that this event code was consumed by an extension, it must
be updated to drop the “s
“, and reference the newly added ExecutionId
event detail.
Note: the Inedo SDK (available since v6.0) is not affected, and extensions built against it do not require updates. However, the Inedo.SDK v1.1 version is available from NuGet going forward.
BuildMaster 6.1 Behavior Change: Resource Credentials’ Environment Usage
In this version, if a Resource Credential is assigned to an environment, any deployment targets that reference the credential must be associated with that environment, otherwise a run time error will occur.
BuildMaster 6.1 Behavior Change: Hiding Legacy Features
In this version, legacy features are hidden from the UI unless configured to be shown on the Advanced Settings page via the Legacy.{FeatureName} settings. Additionally, visiting the Administration > Legacy Features Dashboard and running the detection mechanism will also set the configuration values automatically.
BuildMaster 6.1 Free Edition Licensing Changes
Before v6.0, BuildMaster Free included 5 users, 10 applications, and 5 servers. Beginning with v6.0, BuildMaster Free is now unlimited users, applications, and servers, but all anonymous users are granted “view-only” privileges and all authenticated users act as full administrators (i.e. all users have every permission granted to them and restrictions are ignored).
Important: any Free Edition users that expose their instance to the internet should be aware that this change effectively turns their BuildMaster instance into a public one, where applications, releases, and execution data can be viewed by any user with access to the web application.
Any existing free users who are negatively affected by this change, visit the contact form and we can send you a new key that will effectively be a 5 user key with no server or application restrictions.
BuildMaster 6.1 Multiple License Key Support Removed
Important: Take note of your current license key before upgrading in case the latest license key added is not the key that is currently in use.
Multiple license key support will be removed in this version. On upgrade, BuildMaster will use the latest-added & activated license key as the single license key, and references to all others will be removed. If the wrong key was chosen as the single key, you will have to log-in to MyInedo if you did not take note of the current key.
BuildMaster 6.1 Feature: Rename “Release Packages” to “Builds”
This is effectively a UI-only change. While API arguments or properties that reference “packages” should be considered deprecated, any non-native endpoint
that references them (e.g. /packages/deploy
, packageId
or packageNumber
) will still accept and return those properties.
Going forward, buildId
and buildNumber
should be used.
Compatibility with the Native API may break in this case, however most of the endpoints referenced “builds” originally.
For a word from Inedo’s founder on the reasoning behind this change, check out his latest blog article.
BuildMaster 6.1 Feature: Repository Monitors & Hooks
Support for monitoring Git repository changes at custom intervals and custom plans to execute once they are detected, offerring far more than was possible in existing legacy build triggers. Additionally, support has been added to accept incoming webhook events from GitHub and GitLab. See the documentation for more information and examples, and also the Git extension wiki for hook configuration of a specific host.
BuildMaster 6.1 Feature: Custom Variable Value Rendering
Support for rendering a release or build configuration variable with custom HTML. See the documentation for more information and examples.
BuildMaster 6.1 Feature: CI Badges
Support for generating CI badges and links using the CI Badge API. See the API documentation for more information and examples.
BuildMaster 6.1 Feature: Customer Experience & Improvement Program
Inedo has partnered with Gibraltar Software in order to integrate Loupe with our products as part of our customer success initiative. This program is known as the Customer Experience Improvement Program (CEIP), and this opt-in program offers several benefits to both Inedo and our customers.
This feature is disabled by default in all existing and new installations. Visit the documentation to learn how to opt-in, and more about what kind of data is collected and how Inedo uses it.