Dela via

Implementera en flödesleverantör i en C#-Windows-applikation

Anmärkning

Viss information gäller försläppt produkt, som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

Den här artikeln beskriver hur du skapar en enkel feedprovider som registrerar en feedinnehålls-URI och implementerar gränssnittet IFeedProvider . Metoderna i det här gränssnittet anropas av Widgets Board för att begära anpassade frågesträngsparametrar, vanligtvis för att stödja autentiseringsscenarier. Feedprovidrar kan stödja en enda feed eller flera feeds.

Information om hur du implementerar en feedprovider med C++/WinRT finns i Implementera en feedprovider i en win32-app (C++/WinRT).

Förutsättningar

  • Enheten måste ha aktiverat utvecklarläge. Mer information finns i Aktivera enheten för utveckling.
  • Visual Studio 2022 eller senare med -utveckling för Universal Windows Platform och arbetsbelastning.

Skapa en ny C#-konsolapp

Skapa ett nytt projekt i Visual Studio. I dialogrutan Skapa ett nytt projekt anger du språkfiltret till "C#" och plattformsfiltret till Windows och väljer sedan projektmallen Konsolapp. Ge det nya projektet namnet "ExampleFeedProvider". För den här genomgången kontrollerar du att Placera lösning och projekt i samma katalog är avmarkerat. När du uppmanas till det anger du .NET-målversionen till 6.0.

När projektet läses in, i Solution Explorer högerklicka på projektnamnet och välj Egenskaper. På sidan Allmänt rullar du ned till Måloperativsystem och väljer "Windows". Under Mål os-version väljer du version 10.022631.2787 eller senare.

Observera att den här genomgången använder en konsolapp som visar konsolfönstret när flödet aktiveras för att möjliggöra enkel felsökning. När du är redo att publicera feedproviderappen kan du konvertera konsolprogrammet till ett Windows-program genom att följa stegen i Konvertera konsolappen till en Windows-app.

Lägga till referenser till Windows App SDK NuGet-paketet

Det här exemplet använder det senaste stabila Windows App SDK NuGet-paketet. Högerklicka på Beroenden i Solution Explorer och välj Hantera NuGet-paket.... I NuGet-pakethanteraren väljer du fliken Bläddra och söker efter "Microsoft.WindowsAppSDK". Välj den senaste stabila versionen i listrutan Version och klicka sedan på Installera.

Lägga till en FeedProvider-klass för att hantera feedåtgärder

I Visual Studio högerklickar du på projektet ExampleFeedProvider i Solution Explorer och väljer Lägg till>klass. I dialogrutan Lägg till klass ger du klassen namnet "FeedProvider" och klickar på Lägg till. I den genererade FeedProvider.cs-filen uppdaterar du klassdefinitionen så att den anger att den implementerar gränssnittet IFeedProvider .

Skapa ett CLSID som ska användas för att identifiera feedprovidern för COM-aktivering. Generera ett GUID i Visual Studio genom att gå till Tools –>Skapa GUID-. Spara det här GUID:et i en textfil som ska användas senare när du paketerar feedproviderappen. Ersätt GUID i anteckningarna för klassen FeedProvider som visas i följande exempel.

// FeedProvider.cs
using Microsoft.Windows.Widgets.Feeds.Providers;
...
[ComVisible(true)]
[ComDefaultInterface(typeof(IFeedProvider))]
[Guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")]
public sealed class FeedProvider : IFeedProvider

Implementera IFeedProvider-metoderna

I de kommande avsnitten implementerar vi metoderna i IFeedProvider-gränssnittet .

Anmärkning

Objekt som skickas till återanropsmetoderna i IFeedProvider-gränssnittet är endast garanterade att vara giltiga under återanropet. Du bör inte lagra referenser till dessa objekt eftersom deras beteende utanför kontexten för återanropet är odefinierat.

OnFeedProviderEnabled

Metoden OnFeedProviderEnabled anropas när ett flöde som är associerat med providern skapas av Widgets Board-värden. I implementeringen av den här metoden genererar du en frågesträng med parametrarna som skickas till url:en som tillhandahåller feedinnehållet, inklusive eventuella nödvändiga autentiseringstoken. Skapa en instans av CustomQueryParametersUpdateOptions och skicka in FeedProviderDefinitionId från händelsen args som identifierar feeden som har aktiverats och frågesträngen. Hämta standard-FeedManager och anropa SetCustomQueryParameters för att registrera frågesträngsparametrarna med Widgets Board.

// FeedProvider.cs

public void OnFeedProviderEnabled(FeedProviderEnabledArgs args)
{
    Console.WriteLine($"{args.FeedProviderDefinitionId} feed provider was enabled.");
    var updateOptions = new CustomQueryParametersUpdateOptions(args.FeedProviderDefinitionId, "param1&param2");
    FeedManager.GetDefault().SetCustomQueryParameters(updateOptions);
}

OnFeedProviderDisabled

OnFeedProviderDisabled anropas när Widgets Board märker att alla flöden för den här leverantören har inaktiverats. Feedprovidrar behöver inte utföra några åtgärder som svar på det här metodanropet. Metodanropet kan användas i telemetrisyfte eller för att uppdatera frågesträngsparametrarna eller återkalla autentiseringstoken om det behövs. Om appen bara stöder en enda feedprovider eller om alla feedproviders som stöds av appen har inaktiverats kan appen avslutas som svar på det här återanropet.

// FeedProvider.cs
public void OnFeedProviderDisabled(FeedProviderDisabledArgs args)
{
    Console.WriteLine($"{args.FeedProviderDefinitionId} feed provider was disabled.");
}

OnFeedEnabled, OnFeedDisabled

OnFeedEnabled och OnFeedDisabled anropas av Widgets Board när en feed är aktiverad eller inaktiverad. Feedprovidrar behöver inte utföra några åtgärder som svar på dessa metodanrop. Metodanropet kan användas i telemetrisyfte eller för att uppdatera frågesträngsparametrarna eller återkalla autentiseringstoken om det behövs.

// FeedProvider.cs
public void OnFeedEnabled(FeedEnabledArgs args)
{
    Console.WriteLine($"{args.FeedDefinitionId} feed was enabled.");
}


// FeedProvider.cs
public void OnFeedDisabled(FeedDisabledArgs args)
{
    Console.WriteLine($"{args.FeedDefinitionId} feed was disabled.");
}

VidFörfråganOmAnpassadeFrågeparametrar

OnCustomQueryParametersRequested utlöses när Widgets Board fastställer att de anpassade frågeparametrarna som är associerade med feedprovidern måste uppdateras. Den här metoden kan till exempel aktiveras om åtgärden för att hämta feedinnehåll från fjärrwebbtjänsten misslyckas. Egenskapen FeedProviderDefinitionId för CustomQueryParametersRequestedArgs som skickas till den här metoden anger flödet som frågesträngparametrar begärs för. Providern bör återskapa frågesträngen och skicka tillbaka den till Widgets Board genom att anropa SetCustomQueryParameters.

// FeedProvider.cs

public void OnCustomQueryParametersRequested(CustomQueryParametersRequestedArgs args)
{
    Console.WriteLine($"CustomQueryParamaters were requested for {args.FeedProviderDefinitionId}.");
    var updateOptions = new CustomQueryParametersUpdateOptions(args.FeedProviderDefinitionId, "param1&param2");
    FeedManager.GetDefault().SetCustomQueryParameters(updateOptions);
}

Implementera en klassfabrik som instansierar FeedProvider vid begäran

För att flödesvärden ska kunna kommunicera med vår feedleverantör måste vi anropa CoRegisterClassObject. Den här funktionen kräver att vi skapar en implementering av IClassFactory som skapar ett klassobjekt för klassen FeedProvider . Vi implementerar vår klassfabrik i en fristående hjälpklass.

I Visual Studio högerklickar du på projektet ExampleFeedProvider i Solution Explorer och väljer Lägg till>klass. I dialogrutan Lägg till klass ger du klassen namnet "FactoryHelper" och klickar på Lägg till.

Ersätt innehållet i FactoryHelper.cs-filen med följande kod. Den här koden definierar gränssnittet IClassFactory och implementerar dess två metoder, CreateInstance och LockServer. Den här koden är typisk för implementering av en klassfabrik och är inte specifik för funktionerna i en feedprovider, förutom att vi anger att klassobjektet som skapas implementerar gränssnittet IFeedProvider .

// FactoryHelper.cs
using Microsoft.Windows.Widgets.Feeds.Providers;
using System.Runtime.InteropServices;
using WinRT;

namespace ExampleFeedProvider
{
    namespace Com
    {
        static class Guids
        {
            public const string IClassFactory = "00000001-0000-0000-C000-000000000046";
            public const string IUnknown = "00000000-0000-0000-C000-000000000046";
        }

        [ComImport(), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid(Guids.IClassFactory)]
        internal interface IClassFactory
        {
            [PreserveSig]
            int CreateInstance(IntPtr pUnkOuter, ref Guid riid, out IntPtr ppvObject);
            [PreserveSig]
            int LockServer(bool fLock);
        }

        static class ClassObject
        {
            public static void Register(Guid clsid, object pUnk, out uint cookie)
            {
                [DllImport("ole32.dll")]
                static extern int CoRegisterClassObject(
                    [MarshalAs(UnmanagedType.LPStruct)] Guid rclsid,
                    [MarshalAs(UnmanagedType.IUnknown)] object pUnk,
                    uint dwClsContext,
                    uint flags,
                    out uint lpdwRegister);

                int result = CoRegisterClassObject(clsid, pUnk, 0x4, 0x1, out cookie);
                if (result != 0)
                {
                    Marshal.ThrowExceptionForHR(result);
                }
            }

            public static int Revoke(uint cookie)
            {
                [DllImport("ole32.dll")]
                static extern int CoRevokeClassObject(uint dwRegister);

                return CoRevokeClassObject(cookie);
            }
        }
    }

    internal class FeedProviderFactory<T> : Com.IClassFactory
            where T : IFeedProvider, new()
    {
        public int CreateInstance(IntPtr pUnkOuter, ref Guid riid, out IntPtr ppvObject)
        {
            ppvObject = IntPtr.Zero;

            if (pUnkOuter != IntPtr.Zero)
            {
                Marshal.ThrowExceptionForHR(CLASS_E_NOAGGREGATION);
            }

            if (riid == typeof(T).GUID || riid == Guid.Parse(Com.Guids.IUnknown))
            {
                // Create the instance of the .NET object
                ppvObject = MarshalInspectable<IFeedProvider>.FromManaged(new T());
            }
            else
            {
                // The object that ppvObject points to does not support the
                // interface identified by riid.
                Marshal.ThrowExceptionForHR(E_NOINTERFACE);
            }

            return 0;
        }

        int Com.IClassFactory.LockServer(bool fLock)
        {
            return 0;
        }

        private const int CLASS_E_NOAGGREGATION = -2147221232;
        private const int E_NOINTERFACE = -2147467262;
    }
}

Registrera feedproviderns klassobjekt med OLE

I Program.cs-filen för vårt körbara program anropar vi CoRegisterClassObject för att registrera vår feed-leverantör med OLE, så att Widgets Board kan interagera med den. Ersätt innehållet i Program.cs med följande kod. Detta använder feedproviderfactory-gränssnittet som vi definierade i ett tidigare steg för att registrera hjälpklassen FeedProvider . I felsökningssyfte anropar det här exemplet GetEnabledFeedProviders på standardinstansen FeedManager för att hämta en lista över FeedProviderInfo-objekt som representerar de aktiverade feedprovidrar. Den loopar genom de aktiverade feedprovidrar med egenskapen EnabledFeedDefinitionIds för att visa en lista över alla aktiverade feed-ID:er.

// Program.cs

using Microsoft.Windows.Widgets.Feeds.Providers;
using Microsoft.Windows.Widgets.Providers;
using System; 
using System.Runtime.InteropServices;

namespace ExampleFeedProvider
{

    public static class Program
    {
        [DllImport("kernel32.dll")]
        static extern IntPtr GetConsoleWindow();

        [MTAThread]
        static void Main(string[] args)
        {
            Console.WriteLine("FeedProvider Starting...");
            if (args.Length > 0 && args[0] == "-RegisterProcessAsComServer")
            {
                WinRT.ComWrappersSupport.InitializeComWrappers();

                uint registrationHandle;
                var factory = new FeedProviderFactory<FeedProvider>();
                Com.ClassObject.Register(typeof(FeedProvider).GUID, factory, out registrationHandle);

                Console.WriteLine("Feed Provider registered.");

                var existingFeedProviders = FeedManager.GetDefault().GetEnabledFeedProviders();
                if (existingFeedProviders != null)
                {
                    Console.WriteLine($"There are {existingFeedProviders.Length} FeedProviders currently outstanding:");
                    foreach (var feedProvider in existingFeedProviders)
                    {
                        Console.WriteLine($"  ProviderId: {feedProvider.FeedProviderDefinitionId}, DefinitionIds: ");
                        var m = WidgetManager.GetDefault().GetWidgetIds();
                        if (feedProvider.EnabledFeedDefinitionIds != null)
                        {
                            foreach (var enabledFeedId in feedProvider.EnabledFeedDefinitionIds)
                            {
                                Console.WriteLine($" {enabledFeedId} ");
                            }
                        }
                    }
                }
                if (GetConsoleWindow() != IntPtr.Zero)
                {
                    Console.WriteLine("Press ENTER to exit.");
                    Console.ReadLine();
                }
                else
                {
                    while (true)
                    {
                        // You should fire an event when all the outstanding
                        // FeedProviders have been disabled and exit the app.
                    }
                }
            }
            else
            {
                Console.WriteLine("Not being launched to service Feed Provider... exiting.");
            }
        }
    }
}

Observera att det här kodexemplet importerar funktionen GetConsoleWindow för att avgöra om appen körs som ett konsolprogram, standardbeteendet för den här genomgången. Om funktionen returnerar en giltig pekare skriver vi felsökningsinformation till konsolen. Annars körs appen som en Windows-app. I så fall väntar vi på händelsen som vi anger i metoden OnFeedProviderDisabled när listan över aktiverade feedprovidrar är tom och vi avslutar appen. Information om hur du konverterar exempelkonsolappen till en Windows-app finns i Konvertera konsolappen till en Windows-app.

Förpacka din flödesleverantörsapp

I den aktuella versionen kan endast paketerade appar registreras som feedproviders. Följande steg tar dig igenom processen för att paketera din app och uppdatera appmanifestet för att registrera din app med operativsystemet som en feedprovider.

Skapa ett MSIX-paketeringsprojekt

I Solution Explorerhögerklickar du på lösningen och väljer Lägg till>Nytt projekt.... I dialogrutan Lägg till ett nytt projekt väljer du mallen "Windows Application Packaging Project" och klickar på Nästa. Ange projektnamnet till "ExampleFeedProviderPackage" och klicka på Skapa. När du uppmanas till det anger du målversionen till build 22621 eller senare och klickar på OK. Högerklicka sedan på projektet ExampleFeedProviderPackage och välj Lägg till> projektreferens. Välj projektet ExampleFeedProvider och klicka på OK.

Lägg till paketreferensen för Windows App SDK i paketeringsprojektet

Du måste lägga till en referens till Windows App SDK-nuget-paketet i MSIX-paketeringsprojektet. Dubbelklicka på projektet ExampleFeedProviderPackage i Solution Explorer för att öppna filen ExampleFeedProviderPackage.wapproj. Lägg till följande XML i elementet Project.

<!--ExampleWidgetProviderPackage.wapproj-->
<ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.5.231116003-experimentalpr">
        <IncludeAssets>build</IncludeAssets>
    </PackageReference>  
</ItemGroup>

Anmärkning

Kontrollera att version som anges i elementet PackageReference matchar den senaste stabila versionen som du refererade till i föregående steg.

Om rätt version av Windows App SDK redan är installerad på datorn och du inte vill paketera SDK-körningen i paketet kan du ange paketberoendet i package.appxmanifest-filen för Projektet ExampleFeedProviderPackage.

<!--Package.appxmanifest-->
...
<Dependencies>
...
    <PackageDependency Name="Microsoft.WindowsAppRuntime.1.5.233430000-experimental1" MinVersion="2000.638.7.0" Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" />
...
</Dependencies>
...

Uppdatera paketmanifestet

I Solution Explorer högerklicka på filen Package.appxmanifest och välj Visa kod för att öppna xml-manifestfilen. Därefter måste du lägga till några namnområdesdeklarationer för de apppakettillägg som vi kommer att använda. Lägg till följande namnområdesdefinitioner i elementet Package på den översta nivån.

<!-- Package.appmanifest -->
<Package
  ...
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
  xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"

I elementet Application skapar du ett nytt tomt element med namnet Extensions. Kom ihåg att detta ska komma efter den avslutande taggen för uap:VisualElements.

<!-- Package.appxmanifest -->
<Application>
...
    <Extensions>

    </Extensions>
</Application>

Det första tillägget vi behöver lägga till är ComServer-tillägget. Detta registrerar startpunkten för körprogrammet i operativsystemet. Det här tillägget motsvarar en paketerad app för registrering av en COM-server genom att ange en registernyckel och är inte avsett enbart för widgetleverantörer. Lägg till följande com:Extension-element som ett underordnat element till Extensions-elementet. Ändra GUID i ID-attributet för com:Class-elementet till det GUID som du genererade i ett tidigare steg när du definierade klassen FeedProvider .

<!-- Package.appxmanifest -->
<Extensions>
    <com:Extension Category="windows.comServer">
        <com:ComServer>
            <com:ExeServer Executable="ExampleFeedProvider\ExampleFeedProvider.exe" Arguments="-RegisterProcessAsComServer" DisplayName="C# Feed Provider App">
                <com:Class Id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" DisplayName="FeedProvider" />
            </com:ExeServer>
        </com:ComServer>
    </com:Extension>
</Extensions>

Lägg sedan till tillägget som registrerar appen som en feedprovider. Klistra in elementet uap3:Extension i kodexemplet nedan, som ett underordnat element till Extensions. Ersätt attributet ClassId för elementet COM med det GUID som du använde i föregående steg.

<!-- Package.appxmanifest -->
<Extensions>
    ...
    <uap3:Extension Category="windows.appExtension">
        <uap3:AppExtension Name="com.microsoft.windows.widgets.feeds" DisplayName="ContosoFeed" Id="com.examplewidgets.examplefeed" PublicFolder="Public">
            <uap3:Properties>
                <FeedProvider Icon="ms-appx:Assets\StoreLogo.png" Description="FeedDescription">
                    <Activation>
                        <!-- Apps exports COM interface which implements IFeedProvider -->
                        <CreateInstance ClassId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" />
                    </Activation>
                    <Definitions>
                        <Definition Id="Contoso_Feed"
                            DisplayName="Contoso_Feed Feed"
                            Description="Feed representing Contoso"
                            ContentUri="https://www.contoso.com/"
                            Icon="ms-appx:Images\StoreLogo.png">
                        </Definition>
                        <Definition Id="Fabrikam_Feed"
                            DisplayName="Fabrikam Feed"
                            Description="Feed representing Example"
                            ContentUri="https://www.fabrikam.com/"
                            Icon="ms-appx:Images\StoreLogo.png">
                        </Definition>
                    </Definitions>
                </FeedProvider>
            </uap3:Properties>
        </uap3:AppExtension>
    </uap3:Extension>
</Extensions>

Detaljerade beskrivningar och formatinformation för alla dessa element finns i XML-format för paketmanifest för feedprovider.

Testa din flödesleverantör

Kontrollera att du har valt den arkitektur som matchar utvecklingsdatorn från listrutan Lösningsplattformar, till exempel "x64". Högerklicka på lösningen i Solution Exploreroch välj Build Solution. När detta är klart högerklickar du på ExampleWidgetProviderPackage och väljer Lansera. Konsolappen bör starta vid distributionstillfället och du kommer att se att flöden aktiveras i konsolens utdata. Öppna widgettavlan så bör du se de nya feedarna på flikarna längst upp i feeds-avsnittet.

Felsöka leverantören av flödet

När du har fäst dina feeds startar Widget Platform ditt flödesproviderprogram för att ta emot och skicka relevant information om flödet. Om du vill felsöka flödet som körs kan du antingen koppla ett felsökningsprogram till det program som kör feedprovidern eller så kan du konfigurera Visual Studio för att automatiskt börja felsöka flödesproviderprocessen när den har startats.

För att ansluta till den process som körs:

  1. I Visual Studio klickar du på Felsöka –> Anslut till process.
  2. Filtrera processerna och hitta önskat flödesproviderprogram.
  3. Anslut felsökningsprogrammet.

För att automatiskt koppla felsökaren till processen när den startas:

  1. I Visual Studio klickar du på Felsökning –> Andra felsökningsmål –> Felsöka installerat apppaket.
  2. Filtrera paketen och hitta önskat flödesproviderpaket.
  3. Markera den och markera kryssrutan med texten Starta inte, men felsök min kod när den startas.
  4. Klicka på Bifoga.

Konvertera konsolappen till en Windows-app

Om du vill konvertera konsolappen som skapades i den här genomgången till en Windows-app högerklickar du på projektet ExampleFeedProvider i Solution Explorer och väljer Egenskaper. Under Program-Allmänt ändrar > från "Konsolprogram" till "Windows-program".

En skärmbild som visar projektegenskaperna för C#-feedprovidern med utdatatypen inställd på Windows-program

Publicera din matareleverantörsapp

När du har utvecklat och testat din feedleverantör kan du publicera din app på Microsoft Store för att användarna ska kunna installera dina feeds på sina enheter. Stegvisa anvisningar för att publicera en app finns i Publicera din app i Microsoft Store-.

Feeds Store-samlingen

När din app har publicerats i Microsoft Store kan du begära att din app inkluderas i feeds Store-samlingen som hjälper användare att identifiera appar som innehåller Windows-feeds. För att skicka din begäran, se Skicka ditt flöde/anslagstavla för tillägg till butikssamlingen.