Protocollo ActivateApplication per provider di widget

Articolo
10/05/2023

Questo articolo descrive il formato dei parametri di attivazione della riga di comando per i provider di widget che usano il tipo di attivazione ActivateApplication.

Importante

I provider di widget specificano un metodo di attivazione nel file manifesto del provider widget come descritto nel formato XML del manifesto del pacchetto del provider di widget. È consigliabile che i provider di widget usino il tipo di attivazione CreateInstance e rispondano alle richieste host widget usando i metodi di interfaccia IWidgetProvider anziché usare il metodo di attivazione ActivateApplication. Le informazioni contenute in questo articolo sono fornite per completezza e non sono consigliate per l'uso da parte della maggior parte delle implementazioni del provider di widget.

Stringa di argomenti nella codifica ActivateApplication e base64url

Quando il provider di widget viene attivato, la riga di comando avrà --widget-call= preceduto dal prefisso di codifica base64url negli argomenti della riga di comando.

--widget-call=[base64url]

Ad esempio, la parte base64url in

--widget-call=ew0KICAgICJXaWRnZXRDYWxsIjoiQ3JlYXRlV2lkZ2V0IiwNCiAgICAiV2lkZ2V0Q29udGV4dCI6ew0KICAgICAgICAiSWQiOiI5ODU4MjEwOS1jNmJmLTQzNzItODlkNi04OWY1N2ViNzU0ZjYiLA0KICAgICAgICAiRGVmaW5pdGlvbk5hbWUiOiJQV0FfQ291bnRpbmdfV2lkZ2V0IiwNCiAgICAgICAgIlNpemUiOiJMYXJnZSINCiAgICB9DQp9

viene decodificata in

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

Dettagli del formato della riga di comando

La riga di comando JSON codifica le chiamate ai metodi IWidgetProvider:

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

Ogni attivazione rappresenta una chiamata al metodo. L'oggetto JSON ha un valore WidgetCall con il nome del metodo e quindi un valore per ogni parametro, denominato come nome del parametro, ad eccezione delle maiuscole. Ogni parametro viene mappato come coppia<nome della variabile, valore> all'oggetto JSON. Ad esempio, per il parametro WidgetContext widgetContext del metodo CreateWidget, il WidgetContext viene definito come segue:

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

Nota

I provider di widget devono ignorare i valori dei parametri imprevisti per gestire il caso in cui in futuro vengono aggiunti parametri aggiuntivi.

Viene eseguito il marshalling della chiamata dell'API CreateWidget del provider di widget all'oggetto Json:

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

L'oggetto includerà sempre il valore WidgetCall e tutti i valori dei parametri specificati dal metodo IWidgetProvider.

Esempi di oggetti a cui è stato eseguito il marshalling

{
    "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"
}

Oggetto JSON OnActionInvoked

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

Attivare oggetto JSON

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

Disattivare l'oggetto JSON

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

Oggetto JSON OnWidgetContextChanged

Ad esempio, WidgetSize viene modificato in Medium. In SV2, WidgetSize è l'unica cosa attiva WidgetContextChanged.

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

Condividi tramite