Compartilhar via

IDs do modelo de usuário do aplicativo (AppUserModelIDs)

  • Artigo

As IDs do Modelo de Usuário do Aplicativo (AppUserModelIDs) são usadas extensivamente pela barra de tarefas no Windows 7 e em sistemas posteriores para associar processos, arquivos e janelas a um aplicativo específico. Em alguns casos, é suficiente confiar no AppUserModelID interno atribuído a um processo pelo sistema. No entanto, um aplicativo que possui vários processos ou um aplicativo em execução em um processo de host pode precisar se identificar explicitamente para que possa agrupar suas janelas diferentes em um único botão de barra de tarefas e controlar o conteúdo da Lista de Atalhos desse aplicativo.

Application-Defined e System-Defined AppUserModelIDs

Alguns aplicativos não declaram um AppUserModelID explícito. Eles são opcionais. Nesse caso, o sistema usa uma série de heurísticas para atribuir um AppUserModelID interno. No entanto, há um benefício de desempenho em evitar esses cálculos e um AppUserModelID explícito é a única maneira de garantir uma experiência exata do usuário. Portanto, é altamente recomendável que uma ID explícita seja definida. Os aplicativos não podem recuperar um AppUserModelID atribuído pelo sistema.

Se um aplicativo usar um AppUserModelID explícito, ele também deverá atribuir o mesmo AppUserModelID a todas as janelas ou processos, atalhos e associações de arquivos em execução. Ele também deve usar o AppUserModelID ao personalizar sua Lista de Atalhos por meio de ICustomDestinationList e em todas as chamadas para SHAddToRecentDocs.

Observação

Se os aplicativos não tiverem um AppUserModelID explícito, eles deverão chamar os métodos IApplicationDestinations, IApplicationDocumentLists e ICustomDestinationList , bem como SHAddToRecentDocs de dentro do aplicativo. Se esses métodos forem chamados de outro processo, como um instalador ou desinstalador, o sistema não poderá gerar o AppUserModelID correto e essas chamadas não terão efeito.

 

Os itens a seguir descrevem cenários comuns que exigem um AppUserModelID explícito. Eles também apontam casos em que vários AppUserModelIDs explícitos devem ser usados.

  • Um único arquivo executável com uma interface do usuário com vários modos que aparecem para o usuário como aplicativos separados deve atribuir diferentes AppUserModelIDs a cada modo. Por exemplo, uma parte de um aplicativo que os usuários veem como uma experiência independente que eles podem fixar e iniciar da barra de tarefas separadamente do restante do aplicativo deve ter seu próprio AppUserModelID, separado da experiência de main.

  • Vários atalhos com argumentos diferentes que levam ao que o usuário vê como o mesmo aplicativo devem usar um AppUserModelID para todos os atalhos. Por exemplo, o Windows Internet Explorer tem atalhos diferentes para modos diferentes (como iniciar sem complementos), mas todos eles devem aparecer para o usuário como uma única instância de internet Explorer.

  • Um executável que atua como um processo de host e executa o conteúdo de destino como um aplicativo deve se registrar como um aplicativo host, após o qual ele pode atribuir diferentes AppUserModelIDs a cada experiência percebida que ele hospeda. Como alternativa, o processo de host pode permitir que o programa hospedado defina seus AppUserModelIDs. Em ambos os casos, o processo de host deve manter um registro da origem do AppUserModelIDs, seja ele mesmo ou o aplicativo hospedado. Nesse caso, não há nenhuma experiência do usuário principal do processo de host sem o conteúdo de destino. Exemplos são aplicativos RAIL (Windows Remote Applications Integrated Locally), Java Runtime, RunDLL32.exe ou DLLHost.exe.

    No caso de aplicativos hospedados existentes, o sistema tenta identificar experiências individuais, mas novos aplicativos devem usar AppUserModelIDs explícitos para garantir a experiência do usuário pretendida.

  • Processos cooperativos ou encadeados que fazem parte do mesmo aplicativo devem ter o mesmo AppUserModelID aplicado a cada processo. Os exemplos incluem jogos com um processo inicializador (encadeado) e o Microsoft Reprodutor Multimídia do Windows, que tem uma experiência de primeira execução/instalação em execução em um processo e o aplicativo main em execução em outro processo (cooperativo).

  • Uma extensão de namespace do Shell que atua como um aplicativo separado para mais do que navegar e gerenciar conteúdo no Windows Explorer deve atribuir um AppUserModelID em suas propriedades de pasta. Um exemplo é o Painel de Controle.

  • Em um ambiente de virtualização, como uma estrutura de implantação, o ambiente de virtualização deve atribuir diferentes AppUserModelIDs a cada aplicativo que ele gerencia. Nesses casos, um inicializador de aplicativos usa um processo intermediário para configurar o ambiente e, em seguida, entrega a operação a um processo diferente para executar o aplicativo. Observe que isso faz com que o sistema não consiga relacionar o processo de destino em execução de volta ao atalho porque o atalho aponta para o processo intermediário.

    Se qualquer aplicativo tiver várias janelas, atalhos ou processos, o AppUserModelID atribuído a esse aplicativo também deverá ser aplicado a cada uma dessas partes pelo ambiente de virtualização.

    Um exemplo dessa situação é a estrutura ClickOnce, que atribui corretamente AppUserModelIDs em nome dos aplicativos que gerencia. Como em todos esses ambientes, os aplicativos implantados e gerenciados pelo ClickOnce não devem atribuir AppUserModelIDs explícitos, pois isso entrará em conflito com os AppUserModelIDs atribuídos pelo ClickOnce e levará a resultados inesperados.

Como formar um Application-Defined AppUserModelID

Um aplicativo deve fornecer seu AppUserModelID no formulário a seguir. Ele não pode ter mais de 128 caracteres e não pode conter espaços. Cada seção deve ter maiúsculas e minúsculas.

CompanyName.ProductName.SubProduct.VersionInformation

CompanyName e ProductName sempre devem ser usados, enquanto as SubProduct partes e VersionInformation são opcionais e dependem dos requisitos do aplicativo. SubProductpermite que um aplicativo main que consiste em várias subaplicações forneça um botão de barra de tarefas separado para cada subaplicativo e suas janelas associadas. VersionInformation permite que duas versões de um aplicativo coexistam enquanto são vistas como entidades discretas. Se um aplicativo não se destina a ser usado dessa forma, o VersionInformation deve ser omitido para que uma versão atualizada possa usar o mesmo AppUserModelID que a versão que substituiu.

Onde atribuir um AppUserModelID

Quando um aplicativo usa um ou mais AppUserModelIDs explícitos, ele deve aplicar esses AppUserModelIDs nos seguintes locais e situações:

  • Na propriedade System.AppUserModel.ID do arquivo de atalho do aplicativo. Um atalho (como um IShellLink, CLSID_ShellLink ou um arquivo .lnk) dá suporte a propriedades por meio de IPropertyStore e outros mecanismos de configuração de propriedade usados em todo o Shell. Isso permite que a barra de tarefas identifique o atalho adequado para fixar e garante que as janelas pertencentes ao processo estejam adequadamente associadas a esse botão da barra de tarefas.

    Observação

    A propriedade System.AppUserModel.ID deve ser aplicada a um atalho quando esse atalho é criado. Ao usar o MSI (Microsoft Windows Installer) para instalar o aplicativo, a tabela MsiShortcutProperty permite que o AppUserModelID seja aplicado ao atalho quando ele é criado durante a instalação.

     

  • Como uma propriedade de qualquer uma das janelas em execução do aplicativo. Isso pode ser definido de duas maneiras:

    1. Se janelas diferentes pertencentes a um processo exigirem diferentes AppUserModelIDs para controlar o agrupamento da barra de tarefas, use SHGetPropertyStoreForWindow) para recuperar o repositório de propriedades da janela e definir o AppUserModelID como uma propriedade de janela.
    2. Se todas as janelas no processo usarem o mesmo AppUserModelID, defina o AppUserModelID no processo, embora SetCurrentProcessExplicitAppUserModelID. Um aplicativo deve chamar SetCurrentProcessExplicitAppUserModelID para definir seu AppUserModelID durante a rotina inicial de inicialização de um aplicativo antes que o aplicativo apresente qualquer interface do usuário, faça qualquer manipulação de suas Listas de Atalhos ou faça (ou faça com que o sistema faça) qualquer chamada para SHAddToRecentDocs.

    Um AppUserModelID no nível da janela substitui um AppUserModelID no nível do processo.

    Quando um aplicativo define um AppUserModelID explícito no nível da janela, o aplicativo pode fornecer as especificidades de seu comando de relançamento para o botão da barra de tarefas. Para fornecer essas informações, as seguintes propriedades são usadas:

    Observação

    Se houver um atalho para iniciar o aplicativo, um aplicativo deverá aplicar o AppUserModelID como uma propriedade do atalho em vez de usar as propriedades de relançamento. Nesse caso, a linha de comando, o ícone e o texto do atalho são usados para fornecer as mesmas informações que as propriedades de relançamento.

     

    Um AppUserModelID explícito no nível da janela também pode usar a propriedade System.AppUserModel.PreventPinning para especificar que ela não deve estar disponível para fixação ou relançamento.

  • Em uma chamada para personalizar ou atualizar (ICustomDestinationList), recupere (IApplicationDocumentLists) ou limpe (IApplicationDestinations) a Lista de Atalhos do aplicativo.

  • No registro de associação de arquivos (por meio de seu ProgID) se o aplicativo usar as listas de destino Recentes ou Frequentes geradas automaticamente pelo sistema. Essas informações de associação são referenciadas por SHAddToRecentDocs. Essas informações também são usadas ao adicionar destinos IShellItem a Listas de Atalhos personalizadas por meio de ICustomDestinationList::AppendCategory.

  • Em qualquer chamada, o aplicativo faz diretamente para SHAddToRecentDocs. Se o aplicativo depender da caixa de diálogo de arquivo comum para fazer chamadas para SHAddToRecentDocs em seu nome, essas chamadas poderão deduzir o AppUserModelID explícito somente se o AppUserModelID estiver definido para todo o processo. Se o aplicativo definir AppUserModelIDs em suas janelas em vez de no processo, o aplicativo deverá fazer todas as chamadas para SHAddToRecentDocs em si, com seu AppUserModelID explícito, além de impedir que a caixa de diálogo de arquivo comum faça suas próprias chamadas. Isso deve ser feito sempre que um item é aberto, para garantir que as seções Recentes ou Frequentes da Lista de Atalhos do aplicativo sejam precisas.

Os itens a seguir descrevem cenários comuns e onde aplicar AppUserModelIDs explícitos nesses cenários.

  • Quando um único processo contiver vários aplicativos, use SHGetPropertyStoreForWindow para recuperar o repositório de propriedades da janela e definir o AppUserModelID como uma propriedade de janela.
  • Quando um aplicativo usa vários processos, aplique o AppUserModelID a cada processo. Se você usa o mesmo AppUserModelID em cada processo depende se você deseja que cada processo apareça como parte do aplicativo main ou como entidades individuais.
  • Para separar determinadas janelas de um conjunto no mesmo processo, use o repositório de propriedades da janela para aplicar um único AppUserModelID às janelas que você deseja separar e aplique um AppUserModelID diferente ao processo. Qualquer janela nesse processo que não foi explicitamente rotulada com o AppUserModelID no nível da janela herda o AppUserModelID do processo.
  • Se um tipo de arquivo estiver associado a um aplicativo, atribua o AppUserModelID no registro ProgID do tipo de arquivo. Se um único arquivo executável for iniciado em modos diferentes que aparecem para o usuário como aplicativos distintos, um AppUserModelID separado será necessário para cada modo. Nesse caso, deve haver vários registros ProgID para o tipo de arquivo, cada um com um AppUserModelID diferente.
  • Quando houver vários locais de atalho dos quais um usuário pode iniciar um aplicativo (no menu Iniciar , na área de trabalho ou em outro lugar) recupere o repositório de propriedades do atalho para aplicar um único AppUserModelID a todos os atalhos como propriedades de atalho.
  • Quando uma chamada explícita é feita para SHAddToRecentDocs por um aplicativo, use o AppUserModelID na chamada. Quando a caixa de diálogo de arquivo comum é usada para abrir ou salvar arquivos, SHAddToRecentDocs é chamado pela caixa de diálogo em nome do aplicativo. Essa chamada pode inferir o AppUserModelID explícito do processo. No entanto, se um AppUserModelID explícito for aplicado como uma propriedade de janela, a caixa de diálogo de arquivo comum não poderá determinar o AppUserModelID correto. Nesse caso, o próprio aplicativo deve chamar explicitamente SHAddToRecentDocs e fornecer a ele o AppUserModelID correto. Além disso, o aplicativo deve impedir que a caixa de diálogo de arquivo comum chame SHAddToRecentDocs em seu nome definindo o sinalizador FOS_DONTADDTORECENT no método GetOptions de IFileOpenDialog ou IFileSaveDialog.

Registrando um aplicativo como um processo de host

Um aplicativo pode definir a entrada do Registro IsHostApp para fazer com que o processo desse executável seja considerado um processo de host pela barra de tarefas. Isso afeta o agrupamento e as entradas padrão da Lista de Atalhos.

O exemplo a seguir mostra a entrada do Registro necessária. Observe que a entrada não recebe um valor; sua presença é tudo o que é necessário. É um valor REG_NULL.

HKEY_CLASSES_ROOT
   Applications
      example.exe
         IsHostApp

Se o processo em si ou o arquivo de atalho usado para iniciar o processo tiver um AppUserModelID explícito, a lista de processos do host será ignorada e o aplicativo será tratado como um aplicativo normal pela barra de tarefas. As janelas em execução do aplicativo são agrupadas em um único botão da barra de tarefas e o aplicativo pode ser fixado na barra de tarefas.

Se apenas o nome executável do processo em execução for conhecido, sem um AppUserModelID explícito e esse executável estiver na lista de processos do host, cada instância do processo será tratada como uma entidade separada para o agrupamento da barra de tarefas. O botão da barra de tarefas associado a qualquer instância específica do processo não exibe uma opção de fixar/desafixar ou um ícone de inicialização para uma nova instância do processo. O processo também não está qualificado para inclusão na lista MFU (Uso Mais Usado) do menu Iniciar . No entanto, se o processo foi iniciado por meio de um atalho que contém argumentos de inicialização (geralmente o conteúdo de destino a ser hospedado como o "aplicativo"), o sistema pode determinar a identidade e o aplicativo pode ser fixado e relançado.

Listas de exclusão para fixação da barra de tarefas e listas recentes/frequentes

Aplicativos, processos e janelas podem optar por se tornar indisponíveis para fixar na barra de tarefas ou para inclusão na lista MFU do menu Iniciar . Há três mecanismos para fazer isso:

  1. Adicione a entrada NoStartPage ao registro do aplicativo, conforme mostrado aqui:

    HKEY_CLASSES_ROOT
   Applications
      Example.exe
         NoStartPage

    Os dados associados à entrada NoStartPage são ignorados. Somente a presença da entrada é necessária. Portanto, o tipo ideal para NoStartPage é REG_NONE.

    Observe que qualquer uso de um AppUserModelID explícito substitui a entrada NoStartPage. Se um AppUserModelID explícito for aplicado a um atalho, processo ou janela, ele se tornará fixável e qualificado para a lista MFU do menu Iniciar .

  2. Defina a propriedade System.AppUserModel.PreventPinning em janelas e atalhos. Essa propriedade deve ser definida em uma janela antes da propriedade PKEY_AppUserModel_ID .

  3. Adicione um AppUserModelID explícito como um valor na seguinte subchave do Registro, conforme mostrado aqui:

    HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  FileAssociation
                     NoStartPageAppUserModelIDs
                        AppUserModelID1
                        AppUserModelID2
                        AppUserModelID3

    Cada entrada é um valor REG_NULL com o nome do AppUserModelID. Qualquer AppUserModelID encontrado nesta lista não é fixável e não está qualificado para inclusão na lista MFU do menu Iniciar .

Lembre-se de que determinados arquivos executáveis, bem como atalhos que contêm determinadas cadeias de caracteres em seu nome, são excluídos automaticamente da fixação e inclusão na lista MFU.

Observação

Essa exclusão automática pode ser substituída aplicando um AppUserModelID explícito.

 

Se qualquer uma das cadeias de caracteres a seguir, independentemente do caso, estiver incluída no nome do atalho, o programa não será fixável e não será exibido na lista usada com mais frequência (não aplicável a Windows 10):

  • Documentação
  • Ajuda
  • Instalar
  • Mais informações
  • Leia-me
  • Ler Primeiro
  • Leiame
  • Remover
  • Instalação
  • Suporte
  • What's New

A lista de programas a seguir não é fixável e é excluída da lista usada com mais frequência.

  • Applaunch.exe
  • Control.exe
  • Dfsvc.exe
  • Dllhost.exe
  • Guestmodemsg.exe
  • Hh.exe
  • Install.exe
  • Isuninst.exe
  • Lnkstub.exe
  • Mmc.exe
  • Mshta.exe
  • Msiexec.exe
  • Msoobe.exe
  • Rundll32.exe
  • Setup.exe
  • St5unst.exe
  • Unwise.exe
  • Unwise32.exe
  • Werfault.exe
  • Winhlp32.exe
  • Wlrmdr.exe
  • Wuapp.exe

As listas anteriores são armazenadas nos valores do Registro a seguir.

Observação

Essas listas não devem ser modificadas por aplicativos. Use um dos métodos de lista de exclusão listados anteriormente para a mesma experiência.

 

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  FileAssociation
                     AddRemoveApps
                     HostApps

SetCurrentProcessExplicitAppUserModelID

GetCurrentProcessExplicitAppUserModelID

Extensões da barra de tarefas

ICustomDestinationList::SetAppID

IApplicationDocumentLists::SetAppID

IApplicationDestinations::SetAppID

SHGetPropertyStoreForWindow