Partilhar via

Registrar um aplicativo OEM durante o processo de geração de imagens

  • Artigo

Importante

O Universal Orchestrator fornece funcionalidade aos OEMs para registar uma aplicação durante o processo de imagem, permitindo uma instalação ou atualização rápida e única. Esta instalação acontece dentro de 30 minutos após um utilizador iniciar sessão num novo dispositivo. Acelerar uma aplicação pode ter um impacto negativo no desempenho da experiência inicial para novos dispositivos. Essa funcionalidade só está disponível em versões do Windows que executam a Atualização Cumulativa Não Relacionada à Segurança de novembro de 2024.

Windows 11 23H2 - KB5046732 (Compilação do SO 22631.4541)
Windows 11 24H2 - KB5046740 (Compilação do SO 26100.2454)

Requerimentos

Para se conectar à estrutura do aplicativo acelerado, o aplicativo deve atender aos seguintes requisitos:

  • Deve ser uma aplicação empacotada da Microsoft Store no formato MSIX

  • Deve ter um Nome de Família de Produto (PFN) válido

Registo

Os arquivos de registro são arquivos JSON ASCII que contêm metadados com informações sobre o fluxo acelerado desejado e qualquer direcionamento personalizado do lado do cliente que precise ser executado.

As aplicações aceleradas suportam dois mecanismos para atualizar/adquirir uma aplicação:

  1. Da Microsoft Store usando um ID do Produto (Recomendado)

  2. A partir de um URL que contém um pacote ou conjunto MSIX. Este pacote deve conter uma aplicação empacotada da Store com um Nome de Família de Pacote (PFN) válido. O OEM ou o Proprietário da Aplicação é responsável pela manutenção deste URL.

Cada arquivo de registro deve conter as seguintes propriedades JSON necessárias:

Chave Tipo Descrição
PFN String O nome da família do pacote do aplicativo (exemplo: Microsoft.WindowsStore_8wekyb3d8bbwe)
OEMName String String para representar o OEM que está criando este registro
UpdaterName Corda Nome exclusivo para acompanhar este registo acelerado
Registo-Versão Número A versão deste registro de aplicativo
Fonte String Valores permitidos:

Loja | URL personalizado

Loja - procura a aplicação diretamente a partir da Microsoft Store

CustomURL - procura a aplicação a partir de um URL especificado no valor "Endpoint" do registo da aplicação
Cenário String Valores permitidos:

Atualização | Aquisição | StubAquisição

Atualização - (Não suportado para fluxos CustomURL) tenta atualizar um aplicativo existente para sua versão mais recente disponível. Nenhum trabalho é feito se o aplicativo não estiver presente

Aquisição - tenta adquirir a versão mais recente de um aplicativo.

StubAcquisition - procura adquirir um "stub" da aplicação, caso esteja disponível. Adquire o aplicativo completo se o stub não estiver disponível.
ID do Produto String (Necessário apenas para cenários da Loja)

O ProductId do aplicativo da Loja desejado
Ponto final Sequência de caracteres (Necessário apenas para cenários CustomURL)

Um URI de cadeia de caracteres apontando para um local que hospeda um pacote MSIX. Deve ser um URI SSL que começa com 'https'.

Além disso, as seguintes propriedades opcionais podem ser especificadas para modificar o comportamento da instalação acelerada do aplicativo ou para direcionar o fluxo acelerado para ocorrer somente sob determinadas condições.

Chave Tipo Padrão Descrição
PermitidoNaExperiênciaForaDaCaixa Booleano Falso Se esse aplicativo acelerado deve ser executado durante a OOBE do usuário.

Observação: Tenha cuidado ao definir como verdadeiro, pois isso pode criar restrições de recursos em um dispositivo durante o fluxo da Experiência Fora da Caixa e afetar negativamente o desempenho percebido pelo usuário.
MaxRetryCount Número 1 O número de vezes que este atualizador pode tentar novamente após uma falha.

O valor máximo permitido é: 5
DuraçãoDoTempoLimiteEmMinutos Número 15 A duração em minutos para aguardar até que este atualizador conclua o trabalho.

O valor máximo permitido é: 30
Arquitetura Corda Sem restrições Valores permitidos:

"AMD64" | "ARM64"

Especifica se o trabalho acelerado deve ocorrer apenas para uma arquitetura específica.
Versão Mínima de Build Permitida Número Sem restrições Versões mínimas de compilação do Windows em que o trabalho acelerado é permitido.

Por exemplo, se definido como 22631, o trabalho acelerado é permitido para o Windows 11 23H2 (10.0.22631.x), mas bloqueado para o Windows 11 22H2 (10.0.22621.x)
HonorDeprovisioning Booleano Falso (Aplicável apenas para cenários de aquisição)

Se o aplicativo foi desprovisionado anteriormente, não tente adquiri-lo novamente.
IgnorarSePresente Booleano Falso (Aplicável apenas para cenários de aquisição)

Não execute o trabalho acelerado se alguma versão do aplicativo já estiver presente.
Prioridade Número 100 Um valor numérico de 1 - 100 para indicar a prioridade relativa desta atualização de aplicativo.

Valores mais baixos indicam uma prioridade relativa mais alta em relação a outros aplicativos acelerados.
Regiões excluídas Matriz (String) Sem restrições Uma matriz JSON de cadeias de caracteres para regiões onde este aplicativo NÃO deve ser acelerado.

Cada entrada na matriz corresponde ao código de país ISO 3166-1 de duas letras da região desejada.

Exemplo: ["US", "MX"] impediria esse fluxo em dispositivos onde a região é Estados Unidos ou México.

Nota: Este valor não pode ser usado com IncludedRegions.
Regiões Incluídas Matriz (String) Sem restrições Uma matriz JSON de cadeias de caracteres que indicam uma lista permitida de regiões onde este aplicativo deve ser acelerado.

Cada entrada na matriz corresponde ao código de país ISO 3166-1 de duas letras da região desejada.

Exemplo: ["US", "MX"] permitiria esse fluxo apenas em dispositivos onde a região é Estados Unidos ou México.

Nota: Este valor não pode ser usado com ExcludedRegions.
Incluídas Edições Matriz (número) Sem restrições Uma matriz JSON de números que indica uma lista permitida de edições onde este aplicativo deve ser acelerado.

Cada entrada na matriz corresponde ao código Edition recuperado pelo GetProductInfo API.

Exemplo: [121, 122] para incluir apenas as edições Education e EducationN

Nota: Este valor não pode ser usado com ExcludedEditions.
Edições Excluídas Matriz (número) Sem restrições Uma matriz JSON de números para edições onde este aplicativo NÃO deve ser acelerado.

Cada entrada na matriz corresponde ao código Edition recuperado pelo GetProductInfo API.

Exemplo: [121, 122] para excluir as edições Education e EducationN.

Nota: Este valor não pode ser usado com IncludedEditions.

Amostras

Aquisição de stub em loja, apenas nos EUA e no México, a realizar durante a configuração inicial (OOBE)

{  
    "OEMName": "Contoso",
    "UpdaterName": "OEMApp1",
    "RegistrationVersion":1,  
    "Source": "Store",  
    "Scenario": "StubAcquisition",  
    "PFN": "FakePackageFamilyName",  
    "ProductId": "StoreProductId",  
    "HonorDeprovisioning": true,  
    "AllowedInOobe": true,  
    "IncludedRegions": ["US", "MX"],  
    "Priority": 50  
}

aquisição de aplicativos baseada em URL em dispositivos amd64, excluindo as edições Education e EducationN, apenas no Windows 11 23H2 (not Windows 11 22H2)

{  
    "OEMName": "Contoso",
    "UpdaterName": "OEMApp1",
    "RegistrationVersion":2,  
    "Source": "CustomURL",  
    "Scenario": "Acquisition",  
    "PFN": "FakePackageFamilyName",  
    "Endpoint": "https://<SSL_URI>",   
    "ExcludedEditions": [121, 122],   
    "Architecture": "amd64",   
    "MinimumAllowedBuildVersion": 22631,  
    "Priority": 60 
}

Ferramentas

Para facilitar o processo de registro e fornecer comentários acionáveis sobre os metadados de registro, os OEMs precisam usar os scripts AppOrchestration PowerShell do seguinte local:

microsoft/ms-update-universalorchestrator: scripts e ferramentas para integrar fluxos de atualização baseados no Universal Orchestrator

Os scripts executam a validação básica e realizam o registro para o local apropriado no dispositivo. Em qualquer falha, os scripts lançam uma exceção com os detalhes específicos da falha.

Para usar os scripts:

  1. Transfira os scripts para o seu dispositivo. Na página de repositório do GitHub, você pode optar por fazer o download como um arquivo ZIP e extrair para o seu dispositivo

  2. Em uma janela do PowerShell, execute "Import-Module <PathToScripts>\scripts\AppOrchestration.psd1"

Observação

Esses scripts exigem que o usuário tenha privilégios administrativos no dispositivo e devem ser executados a partir de um console elevado.

Há quatro cmdlets principais usados para o fluxo de registo:

Test-UpdaterRegistration <> CaminhoParaArquivoDeRegistro
Finalidade: Validar o conteúdo de um ficheiro de registo proposto (sem realizar o registo). Permite que o fabricante de equipamento original realize iterações sobre a carga útil de ficheiro de registo sem afetar o dispositivo.

Add-UpdaterRegistration <> PathToRegistrationFile
Objetivo: Validar e preparar o conteúdo de um ficheiro de registo para o local apropriado, para a integração no fluxo acelerado da aplicação.

Get-UpdaterRegistration <OEMName><UpdaterName>
Finalidade: Se OEMName e UpdaterName forem fornecidos, retorne um resumo de um registro existente que corresponda a esses valores. Se essas entradas forem omitidas, retorne um resumo de todos os registros atuais presentes no dispositivo.

Remove-UpdaterRegistration <OEMName><UpdaterName>
Finalidade: Remover qualquer registo que corresponda aos valores OEMName e UpdaterName.

Execução

A estrutura do Universal Orchestrator invoca automaticamente cada um dos aplicativos registrados, em sequência com base na prioridade relativa, nos primeiros 30 minutos após um usuário chegar à área de trabalho em um novo dispositivo (ou durante a OOBE do usuário, se AllowedInOobe estiver definido como true). Cada aplicação registrada adicionada pelo processo de registo OEM será executada até que:

  • Foi instalado com sucesso

  • Ele supera o número máximo de falhas especificado em MaxRetryCount. Após cada falha, o aplicativo entrará em um período de resfriamento de 30 minutos antes de ser tentado novamente.

A estrutura do Universal Orchestrator não executará tentativas aceleradas se qualquer uma das seguintes condições for verdadeira:

  • O dispositivo não tem acesso à Internet.

  • O dispositivo está em uma rede limitada.

  • O dispositivo está com bateria e a economia de bateria está ativada.

  • O dispositivo está configurado com uma política de Tráfego de Rede Restrito do Windows Update.

  • O dispositivo está configurado com uma política de CTA que não está definida para AutoApprove.

Em cada um desses casos, a estrutura do Universal Orchestrator mantém os registros em vigor até que a configuração do dispositivo permita tentativas aceleradas de prosseguir.

Se o registro do aplicativo contiver valores opcionais que bloqueiem o fluxo acelerado (por exemplo, devido ao tipo de edição), a estrutura do Universal Orchestrator considerará essa solicitação de registro atendida e não tentará novamente, mesmo que essas condições possam mudar posteriormente em um dispositivo.

Importante

Tenha cuidado ao optar por agilizar aplicativos por meio dessa estrutura, pois as operações de atualização ocorrem quando o dispositivo pode estar em uso e podem causar um impacto negativo no desempenho da experiência do usuário em um novo dispositivo.