Apex Developer Guide
jNewer Version Available
Set Package Versions for Apex Classes and Triggers
A package version is a number that identifies the set of components uploaded in a package. The version number has the format majorNumber.minorNumber.patchNumber (for example, 2.1.3). The major and minor numbers increase to a chosen value during every major release. The patchNumber is generated and updated only for a patch release.
If you install a new package version, only one instance of each component exists in the package, but the components can emulate older versions. Say that you use a managed package that contains an Apex class. If the publisher decides to deprecate a method in the Apex class and release a new package version, you still see only one instance of the Apex class after installing the new version. However, this Apex class can still emulate the previous version for any code that references the deprecated method in the older version.
By default, an Apex class or trigger that references a managed package is associated with the package version installed when that class or trigger was last saved or deployed. For example, say that you install version 1.0 of Package A, and then create and deploy an Apex class that references that managed package. If you upgrade to version 2.0 of Package A but don’t redeploy the class, then the class remains associated with version 1.0. However, if you upgrade Package A to version 2.0 and then redeploy the class, then the class is now associated with version 2.0.
You can override the default package version settings for an Apex class or trigger. When set to a specific package version, the class or trigger views the package’s global Apex as if that version was installed. Explicitly setting a package version is useful if your class or trigger relies on an older shape of a packaged component. For an example where overriding the default package version is vital to maintain backwards compatibility, see Safely Upgrade Packages from Developer and Subscriber Perspectives.
Set a Package Version in Setup
- From Setup, enter Apex Classes or Apex Triggers in the Quick Find box, and then select Apex Classes or Apex Triggers.
- From the list, click Edit for the Apex class or trigger that you want to configure.
- Click the Version Settings tab.
-
From the Version dropdown for the managed package, select the desired version referenced by
the class or trigger.
The class or trigger continues to use this version even if your install later versions of the managed package, unless you manually update the version setting.
- Click Save.
Set a Package Version in Metadata API
With the PackageVersion field, you specify a managed package version in an Apex class or trigger’s metadata.
-
Identify the managed package’s reference ID. This ID is either the subscriber package ID
for migrated 2GP managed packages or the package namespace for 1GP managed packages.
- From Setup, in the Quick Find box, enter Installed Packages, and select Installed Packages.
- Locate the installed package that you want to reference and click the Package Name.
- On the Installed Package Detail page, locate the Version Setting field. The field identifies the type of reference ID.
- In the Apex class or trigger’s metadata file, add a <packageVersions> element. If your Apex class or trigger references multiple managed packages, include a separate <packageVersions> element for each package.
-
Within the <packageVersions> element, add the
required fields and the desired values.
- For migrated 2GP managed packages, add the packageId field.
- For 1GP managed packages, use the namespace field instead.
Example
Here’s an example declarative metadata definition of an Apex class that references a migrated 2GP managed package.
1<?xml version="1.0" encoding="UTF-8"?>
2<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
3 <apiVersion>66.0</apiVersion>
4 <packageVersions>
5 <majorNumber>3</majorNumber>
6 <minorNumber>0</minorNumber>
7 <packageId>033xx0000000001</packageId>
8 </packageVersions>
9 <status>Active</status>
10</ApexClass>Here’s an example declarative metadata definition of an Apex class that references a 1GP managed package.
1<?xml version="1.0" encoding="UTF-8"?>
2<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
3 <apiVersion>66.0</apiVersion>
4 <packageVersions>
5 <majorNumber>3</majorNumber>
6 <minorNumber>0</minorNumber>
7 <namespace>pkg1</namespace>
8 </packageVersions>
9 <status>Active</status>
10</ApexClass>Set a Package Version in API Requests
-
Identify the managed package’s reference ID. This ID is either the subscriber package ID
for migrated 2GP managed packages or the package namespace for 1GP managed packages.
- From Setup, in the Quick Find box, enter Installed Packages, and select Installed Packages.
- Locate the installed package that you want to reference and click the Package Name.
- On the Installed Package Detail page, locate the Version Setting field. The field identifies the type of reference ID.
If the Version Setting field is set to packageID, then the value of the Package field is the package’s reference ID. If the Version Setting field is set to namespace, then the value of the Namespace field is the package’s reference ID. -
Set the package version header according to the managed package’s reference ID and the
desired package version.
- For REST API calls, use the x-sfdc-packageversion-[packageId/namespace] header. See Package Version Header in the REST API Developer Guide.
- For SOAP API calls, use the PackageVersionHeader header. See PackageVersionHeader in the SOAP API Developer Guide.