NavigationPageCache Support and Limitations

Can I use NavigationCacheMode="Required"?

A Page can be cached in the navigation cache for faster loading of pages by setting the NavigationCacheMode attribute to Required. This works well for pages where the content is easily cached and there are no complications regarding the acquisition or release of limited resources associated with the Page or any of it’s UIElements. E.g. a simple dial control or a grid control showing a small amount of data will benefit from this.

The PdfView, however, does have to manage several system critical resources such as significant memory allocation and file handles. Unfortunately, the XAML UI framework does not supply enough event information for the control to safely hold on to those resources when a Page is unloaded from the visual tree because there is no event signaling that the Page has been ejected from the navigation cache and we cannot let these resources remain acquired until some undetermined time in the future, possibly until the app exits. Even then there is no way to clean up or persist changes properly.

Because of this problem with the Microsoft UI API design we do not recommend using the navigation page cache with pages containing a PdfView. However, if you must use if for whatever reason, in order to behave as best we can we do support the setting but with the following restrictions and considerations:

  • When the Page is removed from the visual tree the PdfView receives an Unloaded event and will unload the document from the PdfView.
  • When a Page is re-mounted into the visual tree the PdfView needs to initialize again and the InitializationCompletedHandler handler will be invoked when it is ready.
  • If a PDF is loaded into the PdfView with the PdfUriSource or PdfFileSource it will be reloaded if the Page is re-mounted into the visual tree.
  • If a PDF is loaded into the PdfView via the ShowDocumentAsync method it will not be reloaded if the Page is re-mounted into the visual tree. This is because of the afore mentioned issue with tracking resources. In this case you should re-load the document in your InitializationCompletedHandler handler.

As you can see, using navigation page cache with controls of large complexity will just add a lot of complexity to you application and we recommend you use a different design until Microsoft provide a method for developers of complex controls to manage limited resources properly.

We have raised this issue with Microsoft and a related one with x:DeferLoadStrategy changing the order of loading events but have received no advice yet that solves the primary issue.

Determining when a control can release resources when NavigationCacheMode is Required:

https://github.com/microsoft/microsoft-ui-xaml/issues/3308

Is it expected that x:DeferLoadStrategy changes order of loading?:

https://github.com/microsoft/microsoft-ui-xaml/issues/3390