UpdateOrchestrator API
UpdateOrchestrator agenda suas atualizações automáticas de software com o impacto do usuário em mente. Essa API permite que você especifique ações, como baixar ou instalar, juntamente com seus requisitos, a fim de executar atualizações em um momento ideal que minimize o impacto presente do usuário. Estas características beneficiam particularmente os sistemas de baixo desempenho com recursos de computação limitados ou mais lentos.
O Windows 20H1 inclui uma solução de primeira geração para casos de uso de atualização automática de software que foram adotados por atualizações do sistema operacional e atualizações de aplicativos da Store e expõe uma versão inicial de 'Acesso limitado' dessa API para um conjunto selecionado de atualizadores de aplicativos de 'modo de usuário', conforme descrito abaixo.
Caraterísticas
Registra dinamicamente atualizadores de software
Invoca atualizadores de software registrados durante os momentos ideais, como durante a ausência do usuário, para atualizar 'aplicativos de modo de usuário'.
Inclui a capacidade de "manter-se acordado" com energia CA para reduzir ainda mais o impacto causado pela ausência do utilizador.
Público do desenvolvedor
Importante
O UpdateOrchestrator API faz parte de um recurso de acesso limitado (consulte classe LimitedAccessFeatures). Para obter mais informações ou solicitar um código de desbloqueio, use o Formulário de Pedido de Token de Acesso LAF.
Use a API do UpdateOrchestrator se você já tiver atualizadores de software em segundo plano para aplicativos de 'modo de usuário' do Win32, como o atualizador da Adobe para o Acrobat Reader ou o Steam da Valve. Essa interface não é necessária para aplicativos UWP/Store, pois a Microsoft Store já aproveita essa funcionalidade para atualizações de software.
Para fornecer a melhor experiência ao cliente, esta versão inicial da API tem como escopo um conjunto selecionado de atualizadores registrados que atendem aos seguintes critérios:
- Atualizações apenas para aplicações de 'modo de utilizador'
- Não envolva BIOS/Firmware/Dispositivo ou drivers de software
- A atualização de BIOS, firmware ou drivers de dispositivo/software que não passaram por um critério de qualidade comum representa um risco substancial, particularmente quando um usuário não está presente.
- Participar do uso desta API implica ser capaz de garantir todo o conteúdo baixado e instalado por seus atualizadores de software em segundo plano nos sistemas dos usuários por meio de auditorias.
A versão inicial da API UpdateOrchestrator como recurso de acesso limitado é apenas para atualizadores que atendem aos critérios acima no momento.
O nosso objetivo é melhorar a funcionalidade desta API e reduzir o impacto de vários atualizadores automáticos de software no Windows. Agradecemos sua contribuição através deste breve de pesquisa para nos ajudar a entender como a API UpdateOrchestrator pode atender melhor às suas necessidades de desenvolvedor.
Acelerando apps OEM através da framework Universal Orchestrator
Importante
O Universal Orchestrator fornece funcionalidade aos OEMs para registrar um aplicativo durante o processo de criação de imagens para executar uma instalação/atualização acelerada única. Esta instalação acontece dentro de 30 minutos após um utilizador iniciar sessão num novo dispositivo. Lembre-se de que agilizar um aplicativo pode ter um impacto negativo no desempenho da experiência pronta 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 versão 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 Loja 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, bem como qualquer direcionamento personalizado do lado do cliente que precise ser executado.
As aplicações aceleradas suportam dois mecanismos para atualizar/adquirir uma aplicação:
- Diretamente da Microsoft Store através de um ProductId (Recomendado)
- A partir de um URL que contém um pacote ou bundle MSIX. Este pacote deve conter uma aplicação da Loja com um Nome de Família do 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 | Cadeia | O Nome da Família do Pacote do aplicativo (por 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 |
| RegistoVersão | Número | A versão deste registro de aplicativo |
| Fonte | Corda | 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 - tenta adquirir um "stub" da aplicação (se estiver 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 | String | (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 |
|---|---|---|---|
| AllowedInOobe | Booleano | Falso | Se esse aplicativo acelerado deve ser executado durante a OOBE do usuário. Observação: Tenha cuidado ao definir isso como true, pois isso pode criar restrições de recursos em um dispositivo durante o fluxo out of Box Experience 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çãoDoTimeoutEmMinutos | Número | 15 | A duração em minutos para aguardar até que este atualizador conclua o trabalho. O valor máximo permitido é: 30 |
| Arquitetura | String | Sem restrições | Valores permitidos: "AMD64" | "Arm64". Especifica se o trabalho acelerado deve ocorrer apenas para uma arquitetura específica. |
| Versão Mínima Permitida de Construção | Número | Sem restrições | Versões mínimas de compilação do Windows em que o trabalho acelerado é permitido. Ex. Se estiver definido como 22631, o trabalho acelerado será 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 tiver sido desprovisionado anteriormente, não tente adquiri-lo novamente. |
| Ignorar se presente | 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 | Array (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 2 letras da região desejada. Ex: ["US", "MX"] impediria esse fluxo em dispositivos onde a região é Estados Unidos ou México.Nota: Este valor não pode ser usado em conjunto com IncludedRegions. |
| Regiões Incluídas | Array (String) | Sem restrições | Uma matriz JSON de cadeias de caracteres que indicam uma lista de regiões permitidas onde esta aplicação deve ser apressada. Cada entrada na matriz corresponde ao código de país ISO 3166-1 de 2 letras da região desejada. Ex: ["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 em conjunto com ExcludedRegions. |
| Edições Incluídas | Matriz (número) | Sem restrições | Uma matriz JSON de números que indica uma lista de permissões de edições onde este aplicativo deve ser acelerado. Cada entrada na matriz corresponde ao código Edition recuperado pelo GetProductInfo API. Ex: [121, 122] para incluir apenas as edições Education e EducationNNota: Este valor não pode ser usado em conjunto 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. Ex: [121, 122] para excluir as edições Education e EducationN.Nota: Este valor não pode ser usado em conjunto com IncludedEditions. |
Amostras
Aquisição de stub nas lojas, apenas nos EUA e México, para execução durante a experiência inicial (OOBE)
{
"RegistrationVersion":1,
"Source": "Store",
"Scenario": "StubAcquisition",
"PFN": "FakePackageFamilyName",
"ProductId": "StoreProductId",
"HonorDeprovisioning": true,
"AllowedInOobe": true,
"IncludedRegions": ["US", "MX"],
"Priority": 50
}
aquisição de aplicações com base em URL em dispositivos amd64, excluindo as edições Education e EducationN, disponível apenas no Windows 11 23H2 (not Windows 11 22H2)
{
"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 registo e fornecer feedback acionável sobre os metadados de registo, os OEMs precisam usar os scripts AppOrchestration PowerShell do seguinte local:
microsoft/ms-update-universalorchestrator: Scripts e ferramentas para integrar-se aos 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:
- 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
- Em uma janela do powershell, execute "Import-Module <PathToScripts>\scripts\AppOrchestration.psd1"
Nota: Esses scripts exigem que o usuário tenha privilégios administrativos no dispositivo e devem ser executados a partir de um console elevado.
Há 4 cmdlets principais usados para o fluxo de registo
Test-UpdaterRegistration <> CaminhoParaArquivoDeRegisto
Finalidade: Validar o conteúdo de um ficheiro de registo proposto (sem realizar o registo). Permite que o fabricante itere sobre a carga útil do ficheiro de registo sem afetar o dispositivo.
Add-UpdaterRegistration <> CaminhoParaFicheiroDeRegisto
Objetivo: Validar e Preparar o conteúdo de um ficheiro de registo para a localização apropriada, para incorporar no fluxo rápido da aplicação
Get-UpdaterRegistration <OEMName><UpdaterName>
Finalidade: Se OEMName e UpdaterName forem fornecidos, retornará um resumo de um registro existente que corresponda a esses valores. Se essas entradas forem omitidas, retorna um resumo de todos os registros atuais presentes no dispositivo.
Remove-UpdaterRegistration <OEMName><UpdaterName<
Finalidade: Anula 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 aplicativo registrado adicionado pelo processo de registro OEM será tentado até que:
- Foi instalado com sucesso
- Ele supera a quantidade máxima de falhas especificadas 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:
- Dispositivo não tem acesso à internet
- O dispositivo está numa rede medida
- O dispositivo está na bateria e a economia de bateria está ativada
- O dispositivo está configurado com uma política de Rede de Tráfego Restrito de Windows Update
- O dispositivo está configurado com uma política de CTA que não está configurada para AutoApprove
Em cada um desses casos, a estrutura do Universal Orchestrator manterá 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.