AppExtensionCatalog
AppExtensionCatalog
AppExtensionCatalog
AppExtensionCatalog
Class
Definition
Provides information about available extensions within an extension group.
public : sealed class AppExtensionCatalog : IAppExtensionCatalogpublic sealed class AppExtensionCatalog : IAppExtensionCatalogPublic NotInheritable Class AppExtensionCatalog Implements IAppExtensionCatalog// You can use this class in JavaScript.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Methods
FindAllAsync() FindAllAsync() FindAllAsync() FindAllAsync()
Provides the list of extensions in the catalog.
public : IAsyncOperation<IVectorView<AppExtension>> FindAllAsync()public IAsyncOperation<IReadOnlyList<AppExtension>> FindAllAsync()Public Function FindAllAsync() As IAsyncOperation( Of IReadOnlyListAppExtension )// You can use this method in JavaScript.
The list of extensions in the catalog. Note that this method returns a list of AppExtensions, not Packages. You can get the Package for each AppExtension with AppExtension.Package.
Remarks
Extensions are scoped by the <uap3:AppExtension Name=...> defined in the extension's Package.appxmanifest file. This method returns the list of extensions installed on the machine that match the <uap3:AppExtension Name=...> defined in the host's Package.appxmanifest file.
You typically call this method when your app launches or resumes from suspension. Then use the events on this class to listen for updates to the extensions in the catalog.
Open(String) Open(String) Open(String) Open(String)
Opens a catalog of extensions.
public : static AppExtensionCatalog Open(PlatForm::String appExtensionName)public static AppExtensionCatalog Open(String appExtensionName)Public Static Function Open(appExtensionName As String) As AppExtensionCatalog// You can use this method in JavaScript.
- appExtensionName
- PlatForm::String String String String
The extension namespace name.
A catalog containing the extensions declared with the specified extension namespace name.
Remarks
Extensions are scoped by the <uap3:AppExtension Name=...> defined in the extension's Package.appxmanifest file. Only extensions that match the <uap3:AppExtension Name=...> defined in the host's Package.appxmanifest file appear in the catalog.
If you have multiple <uap3:AppExtensionHost> declarations in your host app, you need to open a separate catalog for each one.
An instance of the PackageCatalog is required to handle the events so keep a reference to it as long as you need to manage your app extensions.
RequestRemovePackageAsync(String) RequestRemovePackageAsync(String) RequestRemovePackageAsync(String) RequestRemovePackageAsync(String)
Attempts to remove the specified extension package from the machine.
public : IAsyncOperation<PlatForm::Boolean> RequestRemovePackageAsync(PlatForm::String packageFullName)public IAsyncOperation<bool> RequestRemovePackageAsync(String packageFullName)Public Function RequestRemovePackageAsync(packageFullName As String) As IAsyncOperation( Of bool )// You can use this method in JavaScript.
- packageFullName
- PlatForm::String String String String
The name of the package to remove, which you can get from AppExtension.Package.Id.FullName.
Returns true if the request to the user to remove the package was made; otherwise, false.
This function will return false if you try to use a Package name that is not associated with an extension in the AppExtensionCatalog instance. The return value doesn't reflect whether the package was actually removed or not. If the user accepts the prompt to remove the package, you will get a PackageUninstalling event.
Remarks
The user is prompted to allow or deny the package removal. You can only remove packages that contain extensions found in the AppExtensionCatalog instance you make the call from.
The unit of deployment for AppExtensions is the Package. You cannot remove AppExtensions; you can only remove Packages. Packages may contain multiple AppExtensions.
The user may not understand the relationship between AppExtensions and Packages, or between an AppExtension and an app on the machine (because an app may be designed to also serve as an extension). The user may accept the request to remove a package thinking that they are only removing an extension but then find that one of their favorite apps is now gone. Only use this method if you are certain that the AppExtension is the only thing in the package.
Avoid using this method if you do not control the ecosystem of extensions involved. This method is intended for convenience in a closed ecosystem of extensions, such as in an enterprise environment.
Desktop Bridge app extension hosts cannot use this method directly. Desktop Bridge app extension hosts should use their Universal Windows Platform component to manage app extensions.
Events
PackageInstalled PackageInstalled PackageInstalled PackageInstalled
Event that is fired when an extension package is installed.
public : event TypedEventHandler PackageInstalled<AppExtensionCatalog, AppExtensionPackageInstalledEventArgs>public event TypedEventHandler PackageInstalled<AppExtensionCatalog, AppExtensionPackageInstalledEventArgs>Public Event PackageInstalled<AppExtensionCatalog, AppExtensionPackageInstalledEventArgs>// You can use this event in JavaScript.
Remarks
The event argument, AppExtensionPackageInstalledEventArgs.Extensions, contains a list of extensions within the extension package.
Extensions are scoped by the <uap3:AppExtension Name=...> defined in the extension's Package.appxmanifest file. Only extensions that match the <uap3:AppExtension Name=...> defined in the host's Package.appxmanifest file, are in the list of extensions.
An event handler for this event is a good place to examine each app extension for correctness and to provide the user the option to use it.
The unit of deployment for an AppExtension is the Package. That's why this is a Package install event and not an AppExtension install event.
Typically there will only be one extension in a package. However, be prepared to handle the case where there are multiple extensions in the package.
Use AppExtension.Id to distinguish between extensions in the same package. To uniquely identify an extension in your app, consider concatenating AppInfo.AppUserModelId and AppExtension.Id:
_uniqueId = yourAppExtention.AppInfo.AppUserModelId + "!" + yourAppExtention.Id;
This guarantees that each AppExtension has a unique name that you can use to track it with in your app. We recommend using this as a key for your AppExtensions so that you can efficiently and correctly identify if a given AppExtension is one that you already know about.
PackageStatusChanged PackageStatusChanged PackageStatusChanged PackageStatusChanged
Event that is fired when an extension package in the catalog removed, updated, or installed.
public : event TypedEventHandler PackageStatusChanged<AppExtensionCatalog, AppExtensionPackageStatusChangedEventArgs>public event TypedEventHandler PackageStatusChanged<AppExtensionCatalog, AppExtensionPackageStatusChangedEventArgs>Public Event PackageStatusChanged<AppExtensionCatalog, AppExtensionPackageStatusChangedEventArgs>// You can use this event in JavaScript.
Remarks
This event helps you identify when a package is no longer available, valid, or has been modified. Handle this event to determine when an extension may no longer be valid and should be disabled. A common use for this event is to detect whether the app package providing the extension is installed on removable media. If the user removes the media containing the package, this event is raised for that package.
The PackageStatus class provides the possible package status states. Use PackageStatus.VerifyIsOk to determine if the package is in good condition. If it returns false, you can check PackageStatus.LicenseIssue or PackageStatus.PackageOffline and provide special handling for those situations. Typically, if the package state is not Ok, you should disable it. It is good practice to call PackageStatus.VerifyIsOk anytime you are about to load an extension.
Consider handling the this event to provide an indicator in your extension manager UI that the extension is disabled or not usable because there is something wrong with the package.
Continue to handle this event, even if you've determined that there is an issue with a package, because the user may update the package and it may then be Ok to load.
Like PackageUpdating and PackageUninstalling, this event only passes the Package that's status changed. It is up to you to match the Package against the AppExtensions you have loaded to determine which extensions are affected by the status change.
PackageUninstalling PackageUninstalling PackageUninstalling PackageUninstalling
Event that is fired when an extension package is being uninstalled.
public : event TypedEventHandler PackageUninstalling<AppExtensionCatalog, AppExtensionPackageUninstallingEventArgs>public event TypedEventHandler PackageUninstalling<AppExtensionCatalog, AppExtensionPackageUninstallingEventArgs>Public Event PackageUninstalling<AppExtensionCatalog, AppExtensionPackageUninstallingEventArgs>// You can use this event in JavaScript.
Remarks
Update the list of extensions that you are tracking when you handle this event to reflect the ones that have been unloaded. If the user re-installs the package, then a PackageInstalled event will be raised and you can re-add the extensions while handling that event just as you would the addition of any extension.
Like PackageUpdating, this event only passes the package that is being uninstalled and not a list of AppExtensions.
PackageUpdated PackageUpdated PackageUpdated PackageUpdated
Event that is fired when an extension package in the catalog is updated.
public : event TypedEventHandler PackageUpdated<AppExtensionCatalog, AppExtensionPackageUpdatedEventArgs>public event TypedEventHandler PackageUpdated<AppExtensionCatalog, AppExtensionPackageUpdatedEventArgs>Public Event PackageUpdated<AppExtensionCatalog, AppExtensionPackageUpdatedEventArgs>// You can use this event in JavaScript.
Remarks
The event arguments contain a list of extensions within the extension package. Extensions are scoped by the <uap3:AppExtension Name=...> defined in the extension's Package.appxmanifest file. Only extensions that match the <uap3:AppExtension Name=...> defined in the host's Package.appxmanifest file are in the list.
The updated package may include new AppExtensions, and may no longer contain AppExtensions that were there previously. If you are maintaining a list of loaded extensions, the handler for this event is a good place to compare the list of AppExtensions in the new package against your list and then update your list accordingly.
AppExtension properties may have changed during the update. If you cached any of them, this is a good time to check for updates.
Generally the best way to handle this event is to treat it as you do the PackageInstalled event, but update your tracking list of AppExtensions instead of creating a new tracking list.
PackageUpdating PackageUpdating PackageUpdating PackageUpdating
Event that is fired when an extension package is being updated.
public : event TypedEventHandler PackageUpdating<AppExtensionCatalog, AppExtensionPackageUpdatingEventArgs>public event TypedEventHandler PackageUpdating<AppExtensionCatalog, AppExtensionPackageUpdatingEventArgs>Public Event PackageUpdating<AppExtensionCatalog, AppExtensionPackageUpdatingEventArgs>// You can use this event in JavaScript.
Remarks
This event marks when a package update has started. It precedes the PackageUpdated event. In most cases, treat this as you do PackageUninstalling.
A good way to handle this event is to treat the associated extensions within the package as unavailable when you handle PackageUpdating, and then reload them when you handle the PackageUpdated event. The time between these two events is typically less than a second.
The event argument, AppExtensionPackageUpdatingEventArgs.Extensions, only includes the Package and the extension namespace name specified in the extension's Package.appxmanifest file as <uap3:AppExtension Name=...>. It doesn't contain the list of extensions.
When you handle the PackageUpdating event, match the package that is being updated against any extensions that you have loaded from that package so that you can keep track of which extensions are now available. This is why you should keep track of the AppExtensions that you have loaded, the packages to which they belong, and a unique identifier for them that you can use as a key as described in the remarks for AppExtensionCatalog.Open.