Protocolo ActivateApplication do provedor de widget

Artigo
09/02/2023

Este artigo descreve o formato dos parâmetros de ativação de linha de comando para provedores de widgets que usam o tipo de ativação ActivateApplication.

Importante

Os provedores de widget especificam um método de ativação no arquivo de manifesto do provedor de widget, conforme descrito no formato XML do manifesto do pacote do provedor de widget. É recomendável que os provedores de widget usem o tipo de ativação CreateInstance e respondam a solicitações de host de widget usando os métodos de interface IWidgetProvider em vez de usar o método de ativação ActivateApplication. As informações neste artigo são fornecidas para integridade e não são recomendadas para uso pela maioria das implementações do provedor de widget.

Cadeia de caracteres de argumentos na codificação ActivateApplication e base64url

Quando o provedor de widget é ativado, a linha de comando terá --widget-call= prefixado antes da codificação base64url nos argumentos de linha de comando.

--widget-call=[base64url]

Por exemplo, a parte base64url em

--widget-call=ew0KICAgICJXaWRnZXRDYWxsIjoiQ3JlYXRlV2lkZ2V0IiwNCiAgICAiV2lkZ2V0Q29udGV4dCI6ew0KICAgICAgICAiSWQiOiI5ODU4MjEwOS1jNmJmLTQzNzItODlkNi04OWY1N2ViNzU0ZjYiLA0KICAgICAgICAiRGVmaW5pdGlvbk5hbWUiOiJQV0FfQ291bnRpbmdfV2lkZ2V0IiwNCiAgICAgICAgIlNpemUiOiJMYXJnZSINCiAgICB9DQp9

é decodificada em

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

Detalhes do formato de linha de comando

A linha de comando Json codifica chamadas para os métodos IWidgetProvider:

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

Cada ativação representa uma chamada de método. O objeto Json tem um valor WidgetCall com o nome do método e, em seguida, um valor para cada parâmetro, nomeado como o nome do parâmetro, exceto em maiúsculas. Cada parâmetro é mapeado como um par<nome da variável, valor> para o objeto json. Por exemplo, para o parâmetro WidgetContext widgetContext do método CreateWidget, WidgetContext é definido assim:

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

Observação

Os provedores de widget devem ignorar valores de parâmetro inesperados para lidar com o caso em que parâmetros adicionais são adicionados no futuro.

A chamada à API do provedor de widget CreateWidget é empacotada para o objeto Json:

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

O objeto sempre incluirá o valor WidgetCall e todos os valores de parâmetro, conforme especificado pelo método IWidgetProvider.

Exemplos de objetos marshalled

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

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

Ativar objeto Json

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

Desativar objeto Json

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

Objeto Json OnWidgetContextChanged

Por exemplo, WidgetSize é alterado para Médio. No SV2, WidgetSize é a única coisa que dispara o WidgetContextChanged.

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

Compartilhar via