Códigos de saída no Windows além de sucesso/falha: o bitmask do robocopy, os códigos do instalador do msiexec e $LASTEXITCODE

O que é

O robocopy reúne vários fatos independentes de sim/não em um único valor de saída; os valores documentados se combinam como bits (1 copiado, 2 extra, 4 divergente, 8 falhas):

Valor	Significado
0	Nenhum arquivo foi copiado; sem falha; sem divergência (o destino já correspondia à origem)
1	Todos os arquivos foram copiados com sucesso
2	Existem no destino arquivos/diretórios extras que não estão na origem
3	Arquivos foram copiados e existem arquivos extras
5	Arquivos foram copiados e alguns apresentaram divergência
6	Existem arquivos extras e divergentes, mas nada foi copiado e nada falhou
7	Arquivos copiados, houve divergência e havia arquivos extras
8	Vários arquivos não foram copiados

A regra documentada: "Any value equal to or greater than 8 indicates that there was at least one failure during the copy operation" (qualquer valor igual ou maior que 8 indica que houve pelo menos uma falha durante a cópia). Abaixo de 8, o número é apenas informativo e não indica sucesso ou falha.

O msiexec devolve códigos de erro específicos do Windows Installer, dois dos quais são sucessos disfarçados:

Código	Nome	Significado
0	ERROR_SUCCESS	Concluído normalmente
1603	ERROR_INSTALL_FAILURE	Ocorreu um erro fatal durante a instalação
1618	ERROR_INSTALL_ALREADY_RUNNING	Outra instalação já está em andamento
3010	ERROR_SUCCESS_REBOOT_REQUIRED	"A restart is required to complete the install. This message indicates success." (É necessário reiniciar para concluir a instalação; a mensagem indica sucesso.)
1641	ERROR_SUCCESS_REBOOT_INITIATED	"The installer has initiated a restart. This message indicates success." (O instalador iniciou uma reinicialização; a mensagem indica sucesso.)

O $LASTEXITCODE é a janela do PowerShell para o código real de um programa nativo, mas seu valor depende de como o script foi invocado: se chamado diretamente ou com &, permanece inalterado, a menos que o script chame exit ou execute um comando nativo; com pwsh -File, torna-se 1 em caso de exceção não tratada ou o valor especificado em exit, e 0 em caso de sucesso; com pwsh -Command, torna-se 1 se o último comando deixou $? como falso, e 0 caso contrário, o que reduz a 1 qualquer código nativo mais específico.

O sc.exe não usa uma pequena tabela fixa; ele expõe diretamente o código de erro de sistema do Win32, por exemplo 1060 (ERROR_SERVICE_DOES_NOT_EXIST, "The specified service does not exist as an installed service"). Consulte os códigos na referência System Error Codes, em vez de supor uma lista curta e enumerada.

Por que importa

Um script que verifica robocopy ...; if ($LASTEXITCODE -ne 0) { fail } trata de forma inconsistente o caso rotineiro de "nada a copiar" (0) e o de "copiado com sucesso" (1), e também reprova uma execução do msiexec que teve êxito mas exige reinicialização (3010/1641).

Como aplicar

• No robocopy, teste if ($LASTEXITCODE -ge 8) { fail }, e não -ne 0.
• No msiexec, trate 0, 3010 e 1641 como sucesso (agendando uma reinicialização nos dois últimos casos); trate 1603 e 1618 como falhas reais.
• Capture $LASTEXITCODE imediatamente após a chamada nativa, antes que outro comando o sobrescreva, e saiba qual modo de invocação (-File ou -Command) reduz sua granularidade.
• No sc.exe, resolva o resultado numérico consultando a referência de códigos de erro do sistema, em vez de usar um switch com valores fixos no código.

Armadilhas

• Comparar o código do robocopy ou do msiexec com um simples booleano zero/diferente de zero em um pipeline de automação.
• Supor que o modo -Command preserva o código específico de um programa nativo; ele é reduzido a 0 ou 1, a menos que o comando termine com exit $LASTEXITCODE.