ActivateApplication-Protokoll des Widgetanbieters

Artikel
09/11/2023

In diesem Artikel wird das Format der Befehlszeilenaktivierungsparameter für Widgetanbieter beschrieben, die den ActivateApplication-Aktivierungstyp verwenden.

Wichtig

Widgetanbieter geben eine Aktivierungsmethode in der Manifestdatei des Widgetanbieters an, wie im XML-Format des Widgetanbieter-Paketmanifests beschrieben. Es wird empfohlen, dass Widgetanbieter den CreateInstance-Aktivierungstyp verwenden und auf Widgethostanforderungen mit den IWidgetProvider-Schnittstellenmethoden reagieren, anstatt die ActivateApplication-Aktivierungsmethode zu verwenden. Die Informationen in diesem Artikel werden aus Gründen der Vollständigkeit bereitgestellt und nicht für die Verwendung durch die meisten Widgetanbieterimplementierungen empfohlen.

Argumentzeichenfolge in ActivateApplication und base64url-Codierung

Wenn der Widgetanbieter aktiviert ist, hat die Befehlszeile das Präfix --widget-call= vor der base64url-Codierung in den Befehlszeilenargumenten.

--widget-call=[base64url]

Beispiel: der base64url-Teil in

--widget-call=ew0KICAgICJXaWRnZXRDYWxsIjoiQ3JlYXRlV2lkZ2V0IiwNCiAgICAiV2lkZ2V0Q29udGV4dCI6ew0KICAgICAgICAiSWQiOiI5ODU4MjEwOS1jNmJmLTQzNzItODlkNi04OWY1N2ViNzU0ZjYiLA0KICAgICAgICAiRGVmaW5pdGlvbk5hbWUiOiJQV0FfQ291bnRpbmdfV2lkZ2V0IiwNCiAgICAgICAgIlNpemUiOiJMYXJnZSINCiAgICB9DQp9

ist decodiert in

{
    "WidgetCall":"CreateWidget",
    "WidgetContext":{
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

Details zum Befehlszeilenformat

Die Json-Befehlszeile codiert Aufrufe der IWidgetProvider-Methoden:

    interface IWidgetProvider
    {
        void CreateWidget(WidgetContext widgetContext);
        void DeleteWidget(String widgetId);
        void OnActionInvoked(WidgetCallInvokedArgs actionInvokedArgs);
        void OnWidgetContextChanged(WidgetContextChangedArgs contextChangedArgs);
    }

Jede Aktivierung stellt einen Methodenaufruf dar. Das Json-Objekt verfügt über einen WidgetCall-Wert mit dem Methodennamen und dann über einen Wert für jeden Parameter, der als Parametername mit Ausnahme von Großbuchstaben benannt ist. Jeder Parameter wird als Paar <Variablenname, Wert> dem Json-Objekt zugeordnet. Für den Parameter WidgetContext widgetContext der CreateWidget-Methode ist der WidgetContext beispielsweise wie folgt definiert:

    runtimeclass WidgetContext
    {
        String Id { get; };
        String DefinitionId{ get; };
        String Size { get; };
    };

Hinweis

Widgetanbieter sollten unerwartete Parameterwerte ignorieren, um den Fall zu behandeln, in dem in Zukunft zusätzliche Parameter hinzugefügt werden.

Der API-Aufruf des Widgetanbieters CreateWidget wird an das Json-Objekt gemarshallt:

{
    "WidgetCall":"CreateWidget",
    "WidgetContext":{
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

Das Objekt enthält immer den WidgetCall-Wert und alle Parameterwerte, wie von der IWidgetProvider -Methode angegeben.

Beispiele für gemarshallte Objekte

{
    "WidgetCall":"CreateWidget",
    "WidgetContext":{
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

{
  "WidgetId": "1AC74363-177B-4CD2-995F-3B25AEEA3FF4",
  "WidgetCall": "DeleteWidget",
  "CustomState": "usedata"
}

OnActionInvoked-Json-Objekt

{
    "WidgetCall": "OnActionInvoked",
    "Args":{
        "Verb": "Verb String",
        "Data": "Data Details",
        "CustomState": "usedata",
        "WidgetContext": {
            "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
            "DefinitionId":"PWA_Counting_Widget",
            "Size":"Large"
        }
    }
}

Json-Objekt aktivieren

{
    "WidgetCall": "Activate",
    "WidgetContext": {
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

Json-Objekt deaktivieren

{
    "WidgetCall": "Deactivate",
    "WidgetId":"98582109-c6bf-4372-89d6-89f57eb754f6"
}

OnWidgetContextChanged-Json-Object

Beispielsweise wird WidgetSize in „Mittel“ geändert. In SV2 ist WidgetSize das Einzige, was WidgetContextChanged triggert.

{
  "WidgetCall": "OnWidgetContextChanged",
  "Args":{
    "WidgetContext":{
            "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
            "DefinitionId":"PWA_Counting_Widget",
            "Size":"Medium"
        }
  }
}

Teilen über