Porting UWP UpdateTask to a Windows App SDK 1.0.0 / WinUI desktop app (packaged, wap)

[JosHuybrighs]

I am porting a UWP/Desktop-Bridge app to WinUI 3 desktop (packaged using a wap project) and have problems adding a windows.updateTask to the new environment. I am not sure in how far Windows App SDK 1.0.0 supports updateTask but the reason I want to have this is that the updateTask would automatically execute some migration code at the moment the old 'uwp' app is updated to the winUI desktop version (before the user would launch the new version).

The issue I have is that I don't know how to create the updateTask project. I read various documents about this and what I found out is that the updateTask must be a OOP background task, that it needs a Windows Runtime Component (which isn't available in VS22 for C#), and that I probably also need a hosting process, which is also unclear for me how to create that one.

Any hints on how to do this is appreciated.

[DrusTheAxe]

How's this?

Run a background task when your UWP app is updated

NOTE: Replace "UWP app" in that title with "package". When a package is updated for a user the package's windows.updateTask extensions (if any) are run.

You don't install "apps". You install "packages". Packages are the unit of distribution and deployment. Packages can contain applications (among other things). Technically you don't install apps, you install packages. That's all sophistry to an average user of course, but for developers things make more sense when not overly simplified :-)

[JosHuybrighs]

@DrusTheAxe Thanks for the feedback.

The problem with the mentioned documentation (Run a background task when your UWP app is updated) is that it unfortunately doesn't work with Visual Studio 2022 and a packaged WinUI Desktop app (or package if you want) that is using C#.

I therefore did some further investigation and finally got it working by doing the following:

Step 1: Add a Windows Runtime Component project to your solution and add all your background task classes in there.
Since there is currently no template in Visual Studio 2022 for creating a C# Windows Runtime Component project you must choose a C# 'Class Library' project.
When done, add NuGet package: Microsoft.Windows.CsWinRT.
Then, edit the project file as follows in order to change it into a Windows Runtime Component project (I am targeting NET6.0):

<Project Sdk="Microsoft.NET.Sdk">
	<PropertyGroup>
		<TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
		<Platforms>x64;x86</Platforms>
		<RuntimeIdentifiers>win10-x86;win10-x64</RuntimeIdentifiers>
	</PropertyGroup>

	<PropertyGroup>
		<CsWinRTComponent>true</CsWinRTComponent>
		<CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
	</PropertyGroup>	
	
	<ItemGroup>
		<PackageReference Include="Microsoft.Windows.CsWinRT" Version="1.6.1" />
	</ItemGroup>
	
	<ItemGroup>
		<None Update="WinRT.Host.runtimeconfig.json">
			<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
		</None>
	</ItemGroup>

</Project>

WinRT.Host.runtimeconfig.json looks as follows:

{
    "runtimeOptions": {
        "tfm": "net6.0",
        "rollForward": "LatestMinor",
        "framework": {
            "name": "Microsoft.NETCore.App",
            "version": "6.0.0"
        }
    }
}

Then, add all of your background tasks to the project. My UpdateTask must only register my other background tasks and so looks as follows:

using System;
using Windows.ApplicationModel.Background;
using Windows.Data.Xml.Dom;
using Windows.UI.Notifications;

namespace SyncFolder.BackgroundTasks
{
    public sealed class UpdateTask : IBackgroundTask
    {
        public void Run(IBackgroundTaskInstance taskInstance)
        {
            var deferral = taskInstance.GetDeferral();
            try
            {
                // Your app migration/update code here
                RegisterBackgroundTasks();
                SendToast();
            }
            catch (Exception ex)
            { }
            finally
            {
                deferral.Complete();
            }
        }

        private void RegisterBackgroundTasks()
        {
            // Background task registration
            ... 
        }

        private static void SendToast()
        {
            XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(ToastTemplateType.ToastImageAndText02);
            XmlNodeList textElements = toastXml.GetElementsByTagName("text");
            textElements[0].AppendChild(toastXml.CreateTextNode("SyncFolder"));
            textElements[1].AppendChild(toastXml.CreateTextNode("SyncFolder has been updated"));
            ToastNotification notification = new(toastXml);
            ToastNotificationManager.CreateToastNotifier().Show(notification);
        }
    }
}

Step 2: Add a reference in your main app project to the above Windows Runtime Component project.

Step 3: Change the manifest file in the package project to include the UpdateTask (and possible other background tasks) and
add the necessary extensions in there to define the InProcessServer that is required to host the background components.

The key entries in the manifest file in my case (1 updateTask and 1 background task) then look as follows:

<Applications>
  <Application Id="App"
		Executable="$targetnametoken$.exe"
		EntryPoint="$targetentrypoint$">
	...
	<Extensions>
		<Extension Category="windows.backgroundTasks" EntryPoint="SyncFolder.BackgroundTasks.ScheduleBackupTask">
		  <BackgroundTasks>
			<Task Type="timer"/>
		  </BackgroundTasks>
		</Extension>
		<Extension Category="windows.updateTask" EntryPoint="SyncFolder.BackgroundTasks.UpdateTask"/>
	</Extensions>
  </Application>
</Applications>

<!-- To host the background task components, you must add these activatable class entries -->
<Extensions>
  <Extension Category="windows.activatableClass.inProcessServer">
	<InProcessServer>
		<Path>SyncFolder\WinRT.Host.dll</Path>
		<ActivatableClass ActivatableClassId="SyncFolder.BackgroundTasks.ScheduleBackupTask" ThreadingModel="both"/>
	</InProcessServer>
  </Extension>
  <Extension Category="windows.activatableClass.inProcessServer">
	<InProcessServer>
		<Path>SyncFolder\WinRT.Host.dll</Path>
		<ActivatableClass ActivatableClassId="SyncFolder.BackgroundTasks.UpdateTask" ThreadingModel="both"/>
	</InProcessServer>
  </Extension>
</Extensions>

<Capabilities>
  <rescap:Capability Name="runFullTrust" />
</Capabilities>

To summarize: updateTask indeed is supported in a WinUI desktop package, but Microsoft's documentation about the subject should be improved considerably.
Maybe there are simpler ways to achieve this, and so I am very interested in learning how.

[angelazhangmsft]

@JosHuybrighs that's correct, the C#/WinRT authoring support is the supported way to implement Windows Runtime Components. There are some project support improvements we are looking into in this area.

Thanks for the feedback on the docs, I've opened MicrosoftDocs/windows-dev-docs#3770 to add a pointer from the existing UWP OOP background task docs to the new support. I think it might also help to add a pointer from existing Windows Runtime Component UWP docs to the C#/WinRT docs for authoring Windows Runtime Components.