Exemplo de criação de pacote único

Artigo
06/13/2023

O exemplo PUASample.msi é um exemplo de um pacote do Windows Installer 5.0 de dupla finalidade que pode ser instalado no contexto de instalação de cada usuário ou computador no Windows Server 2008 R2 e no Windows 7. Este pacote de exemplo segue as diretrizes de desenvolvimento descritas em Criação de Pacote Único.

Obtendo uma cópia do exemplo

Uma cópia deste exemplo e um editor de tabela de banco de dados do Windows Installer, Orca.exe, estão nos Componentes do SDK do Windows para Desenvolvedores do Windows Installer. O editor de exemplo e tabela é fornecido com o Kit de Desenvolvimento de Software do Windows para Windows Server 2008 R2 e o Windows 7 como os arquivos de instalação do Windows Installer PUASample1.msi e Orca.msi.

Requisitos do Sistema

O editor de banco de dados, Orca.exe, requer o Windows Server 2008 R2 e anteriores e o Windows 7 e anteriores. O pacote de dupla finalidade, PUASample1.msi, pode ser instalado no contexto de instalação de cada computador ou usuário no Windows Server 2008 R2 e no Windows 7. PUASample1.msi só pode ser instalado no contexto de cada computador no Windows Server 2008 e anterior e no Windows Vista e anteriores. Você pode instalar o editor de banco de dados para examinar o conteúdo do PUASample1.msi sem instalar o exemplo. Para instalar os pacotes de exemplo ou editor, verifique se a política DisableMSI não está definida como um valor que bloqueia as instalações do aplicativo.

Identificando um pacote de dupla finalidade

Pacotes de dupla finalidade devem inicializar o valor da propriedade MSIINSTALLPERUSER como 1. Isso identifica o pacote como possível de ser instalado no contexto de cada computador ou usuário no Windows Server 2008 R2 e no Windows 7. Defina a propriedade MSIINSTALLPERUSER no pacote somente se ela tiver sido gravada seguindo as diretrizes de desenvolvimento descritas em Criação de Pacote Único e se você pretende fornecer aos usuários a opção de instalar o pacote no contexto de cada usuário ou computador. Um pacote de dupla finalidade também deve inicializar o valor da propriedade ALLUSERS como 2. Isso especifica cada usuário como o contexto de instalação padrão para o aplicativo. Se o valor da propriedade ALLUSERS for um valor diferente de 2, o Windows Installer ignorará a propriedade MSIINSTALLPERUSER.

Use um editor de banco de dados do Windows Installer, como Orca.exe, para examinar o conteúdo de PUASample1.msi. A tabela Property no pacote de exemplo contém as duas entradas a seguir.

Tabela Property (parcial)

Propriedade	Valor
ALLUSERS	2
MSIINSTALLPERUSER	1

Caixa de Diálogo personalizada para Contexto de Instalação

A interface do usuário do pacote de exemplo inclui um exemplo de uma caixa de diálogo personalizada, VerifyReadyDialog, que permite que os usuários selecionem o contexto de instalação de cada usuário ou computador no momento da instalação. A tabela Dialog contém um registro que descreve a caixa de diálogo VerifyReadyDialog. O valor inserido no campo Atributos é 39 porque essa caixa de diálogo usa os bits de estilo de diálogomsidbDialogAttributesVisible (1), msidbDialogAttributesModal (2), msidbDialogAttributesMinimize (4) e msidbDialogAttributesTrackDiskSpace (32). A barra de título da caixa de diálogo exibe um título fornecido pelo valor da propriedade ProductName.

Tabela Dialog (parcial)

caixa de diálogo	HCentering	VCentering	Largura	Altura	Atributos	Título	Control_First	Control_Default	Control_Cancel
VerifyReadyDialog	50	50	480	280	39	[ProductName]	InstallPerUser	Avançar	Cancelar

A tabela Control contém entradas para os controles exibidos pela caixa de diálogo VerifyReadyDialog. A caixa de diálogo exibe controles PushButton e um controle Text. Todos os controles usam os atributos de controlemsidbControlAttributesEnabled (2) e msidbControlAttributesVisible (1). O controle InstallPerMachine também usa o atributo de controle ElevationShield, msidbControlAttributesElevationShield (8388608.) Esse atributo de controle adiciona o ícone de elevação (ícone de escudo) do UAC (Controle de Conta de Usuário) ao controle InstallPerMachine e informa ao usuário que as credenciais do UAC são necessárias para instalar o aplicativo no contexto de cada computador. O valor no campo Text da tabela Control é o estilo de texto e o texto exibidos pelo controle. Confira a descrição do campo Text no tópico Tabela Contorl para obter mais informações sobre como adicionar texto a um controle usando estilos predefinidos.

Tabela Control (parcial)

Dialog_	Control	Tipo	Atributo	Texto	Control_Next
VerifyReadyDialog	Cancelar	PushButton	3	{\Tahoma10}&Cancel	Avançar
VerifyReadyDialog	Anterior	PushButton	3	{\Tahoma10}<<&Previous	Cancelar
VerifyReadyDialog	Avançar	PushButton	3	{\Tahoma10}&Avançar >>	InstallPerUser
VerifyReadyDialog	Text2	Texto	3	Você está pronto para concluir sua instalação suspensa?
VerifyReadyDialog	InstallPerUser	PushButton	3	{\Tahoma10}Instalar somente para &mim	InstallPerMachine
VerifyReadyDialog	InstallPerMachine	PushButton	8388611	{\Tahoma10}Instalar para &Todos	Anterior
VerifyReadyDialog	Cancelar	PushButton	3	{\Tahoma10}&Cancel	Avançar

A tabela ControlEvent especifica o ControlEvents, ou as ações, que o instalador executa quando o usuário interage com um controle. Quando um usuário ativa o botão InstallPerUser, a interface do usuário exibe uma caixa de diálogo OutOfDisk se a propriedade OutOfDiskSpace for 1, define o valor da propriedade MSIINSTALLPERUSER como 1, define o valor da propriedade ALLUSERS como 2, define a propriedade MSIFASTINSTALL como 1 e retorna . Como a propriedade MSIFASTINSTALL está definida, nenhum ponto de Restauração do Sistema é gerado para a instalação. Quando um usuário ativa o botão InstallPerMachine, a interface do usuário exibe uma caixa de diálogo OutOfDisk se a propriedade OutOfDiskSpace for 1, define o valor da propriedade ALLUSERS como 1 e retorna.

Tabela ControlEvent (parcial)

Dialog_	Control_	Evento	Argumento	Condição	Order
VerifyReadyDialog	InstallPerUser	SpawnDialog	OutOfDisk	OutOfDiskSpace = 1	1
VerifyReadyDialog	InstallPerUser	EndDialog	Retorno	OutOfDiskSpace <> 1	5
VerifyReadyDialog	InstallPerUser	[MSIINSTALLPERUSER]	1	1	2
VerifyReadyDialog	InstallPerUser	[ALLUSERS]	2	1	3
VerifyReadyDialog	InstallPerMachine	SpawnDialog	OutOfDisk	OutOfDiskSpace = 1	1
VerifyReadyDialog	InstallPerMachine	EndDialog	Retorno	OutOfDiskSpace <> 1	3
VerifyReadyDialog	InstallPerMachine	[ALLUSERS]	1	1	2
VerifyReadyDialog	InstallPerUser	[MSIFASTINSTALL]	1	1	4

O controle InstallPerUser deve ser removido da interface do usuário de qualquer instalação usando uma versão do Windows Installer anterior ao Windows Installer 5.0. A tabela ControlCondition no pacote de exemplo contém quatro entradas que desabilitam e ocultam o controle InstallPerUser se a versão atual é menor que o Windows Installer 5.0. A tabela usa o valor da propriedade VersionMsi e a sintaxe da instrução condicional para definir essa condição. A ação especificada no campo Action será executada somente se a instrução no campo Condition for verdadeira.

Tabela ControlCondition (parcial)

Dialog_	Control_	Ação	Condição
VerifyReadyDialog	InstallPerUser	Habilitar	VersionMsi >= "5.00"
VerifyReadyDialog	InstallPerUser	Desabilitar	VersionMsi < "5.00"
VerifyReadyDialog	InstallPerUser	Mostrar	VersionMsi >= "5.00"
VerifyReadyDialog	InstallPerUser	Ocultar	VersionMsi < "5.00"

Como especificar a estrutura de diretório

Use o editor de banco de dados para examinar a tabela Directory do PUASample1.msi. O registro da tabela Directory com uma cadeia de caracteres vazia em seu campo Directory_Parent representa o diretório raiz das árvores de diretório de origem e de destino. Se a propriedade TARGETDIR for indefinida, o instalador definirá seu valor no momento da instalação como o valor da propriedade ROOTDRIVE. Se a propriedade SourceDir for indefinida, o instalador definirá seu valor como o local do diretório que contém o pacote do Windows Installer (arquivo .msi). Os nomes de diretório são especificados usando o formato curto|longo.

Tabela Directory (parcial)

Diretório	Directory_Parent	DefaultDir
TARGETDIR		SourceDir
ProgramFilesFolder	TARGETDIR	.
ProgramMenuFolder	TARGETDIR	.
INSTALLLOCATION	MyVendor	Sample1\|MSDN-PUASample1
MyVendor	ProgramFilesFolder	Msft\|Microsoft

Na origem, essa tabela Directory é resolvida para os caminhos de diretório a seguir.

\[SourceDir\]\\Msft\\Sample1 \[SourceDir\]

No destino, a tabela Directory é resolvida para os caminhos na tabela a seguir. O instalador define os valores das propriedades ProgramFilesFolder e ProgramMenuFolder como locais que dependem do contexto de instalação e dependendo de o sistema ser versões de 32 ou 64 bits do Windows Server 2008 R2 e do Windows 7. Os caminhos para as pastas de destino dependem de o usuário selecionar uma instalação em cada usuário ou computador.

Contexto de instalação	Sistema	Caminhos de exemplo
Por computador	Windows Server 2008 R2 e Windows 7 Versão de 32 bits	%ProgramFiles%\Msft\Sample1 %ALLUSERSPROFILE%\Microsoft\Windows\Start Menu\Programs
Por computador	Windows Server 2008 R2 e Windows 7 Versão de 64 bits	%ProgramFiles(x86)%\Msft\Sample1 %ALLUSERSPROFILE%\Microsoft\Windows\Start Menu\Programs
Por Usuário	Windows Server 2008 R2 e Windows 7 Versão de 32 bits ou 64 bits	%USERPROFILE%\AppData\Local\Programs\Msft\Sample1 %APPDATA%\Microsoft\Windows\Start Menu\Programs

Os aplicativos de cada usuário devem ser armazenados em subpastas na pasta Programas especificada pelo valor da propriedade ProgramFilesFolder. Normalmente, o caminho para o aplicativo assume a forma a seguir.

%LOCALAPPDATA%\Programs\ISV name\AppName.

Os dados de configuração de cada usuário devem ser armazenados na pasta Programas especificada pelo valor da propriedade ProgramMenuFolder. Normalmente, essa pasta está localizada no caminho a seguir.

%APPDATA%\Microsoft\Windows\Start Menu\Programs

Se estiver instalando componentes do Pacote do Windows Installer de 32 bits, use a propriedade ProgramFilesFolder e CommonFilesFolder na tabela Directory. Se estiver instalando componentes do Pacote do Windows Installer de 64 bits, use as propriedades ProgramFiles64Folder e CommonFiles64Folder. Se o aplicativo contiver versões de 32 bits e 64 bits do mesmo componente, com o mesmo nome, faça com que essas versões sejam salvas em diretórios diferentes ou forneça nomes diferentes.

A tabela Directory a seguir fornece um exemplo de um layout de diretório compatível com um pacote que inclui componentes de 32 bits e 64 bits e inclui alguns componentes que são compartilhados entre aplicativos.

Diretório	Directory_Parent	DefaultDir
TARGETDIR		SourceDir
ProgramFilesFolder	TARGETDIR	.:Prog32
ProgramFiles64Folder	TARGETDIR	.:Prog64
CommonFilesFolder	TARGETDIR	.:Share32
CommonFiles64Folder	TARGETDIR	.:Share64
ProgramMenuFolder	TARGETDIR	.:Sample1\|MSDN-PUASample1
INSTALLLOCATION	MyVendor	Sample1\|MSDN-PUASample1
INSTALLLOCATIONX64	Vendorx64	Sample1\|MSDN-PUASample1
SHAREDLOCATION	ShVendor	Sample1\|MSDN-PUASample1
SHAREDLOCATIONX64	ShVendorx64	Sample1\|MSDN-PUASample1
MyVendor	ProgramFilesFolder	Msft\|Microsoft
Vendorx64	ProgramFiles64Folder	Msft\|Microsoft
ShVendor	CommonFilesFolder	Msft\|Microsoft
ShVendorx64	CommonFiles64Folder	Msft\|Microsoft
Shrx86	SHAREDLOCATION	x32\| componentes de 32 bits
Shrx64	SHAREDLOCATIONX64	x64\| componentes de 64 bits
Binx86	INSTALLLOCATION	x32\| componentes de 32 bits
Binx64	INSTALLLOCATIONX64	x64\| componentes de 64 bits
App32	Binx86	myapp\|componentes de 32 bits não compartilhados
App64	Binx64	myapp\|componentes de 64 bits não compartilhados
Share32	Shrx86	shared \| componentes de 32 bits compartilhados
Share64	Shrx64	shared \| componentes de 64 bits compartilhados

Na origem, essa tabela Directory é resolvida para os caminhos de diretório a seguir.

\[SourceDir\]Prog32\\Msft\\Sample1\\x32\\myapp \[SourceDir\]Share32\\Common Files\\Msft\\Sample1\\x32\\shared \[SourceDir\]Prog64\\Msft\\Sample1\\x64\\myapp \[SourceDir\]Share64\\Common Files\\Msft\\Sample1\\x64\\shared \[SourceDir\]Sample1

No destino, essa tabela Directory é resolvida para os caminhos de diretório a seguir. Os caminhos de destino dependem do contexto de instalação e do sistema.

Contexto de instalação	Sistema	Caminhos de exemplo
Por computador	Windows Server 2008 R2 e Windows 7 Versão de 32 bits	%ProgramFiles%\Msft\Sample1\x32\myapp %ProgramFiles%\Common Files\Msft\Sample1\x32\shared %ProgramFiles(x86)%\Msft\Sample1\x64\myapp %ProgramFiles(x86)%\Common Files\Msft\Sample1\x64\shared %ProgramData%\Microsoft\Windows\Start Menu\Programs\Sample1
Por computador	Windows Server 2008 R2 e Windows 7 Versão de 64 bits	%ProgramFiles(x86)%\Msft\Sample1\x32\myapp %ProgramFiles(x86)%\Common Files\Msft\Sample1\x32\shared %ProgramFiles%\Msft\Sample1\x64\myapp %ProgramFiles%\Common Files\Msft\Sample1\x64\shared %ProgramData%\Microsoft\Windows\Start Menu\Programs\Sample1
Por Usuário	Windows Server 2008 R2 e Windows 7 Versão de 32 bits ou 64 bits	%LOCALAPPDATA%\Programs\Msft\Sample1\x32\myapp %LOCALAPPDATA%\Programs\Common\Msft\Sample1\x32\shared %LOCALAPPDATA%\Programs\Msft\Sample1\x64\myapp %LOCALAPPDATA%\Programs\Common\Msft\Sample1\x64\shared %APPDATA%\Microsoft\Windows\Start Menu\Programs\Sample1

Registro de aplicativo

O PUASample.msi adiciona uma subchave à chave do registro de Caminhos do Aplicativo para o aplicativo e executa registros que permitem que as informações do aplicativo sejam salvas no registro nessa chave. Para obter mais informações sobre caminhos de aplicativo e registro de aplicativo, confira a seção PerceivedTypes, SystemFileAssociations e Registro de Aplicativo na seção extensibilidade do shell do Guia do Desenvolvedor do Shell. No momento da instalação, o usuário toma a decisão de instalar o aplicativo no contexto de instalação de cada usuário ou computador. No momento em que o pacote de dupla finalidade é criado, o desenvolvedor do pacote não pode saber se os registros devem ser executados nas chaves HKEY_LOCAL_MACHINE ou HKEY_CURRENT_USER.

O desenvolvedor do pacote define o identificador de arquivo para o arquivo executável do aplicativo no campo File da Tabela File.

Tabela File (parcial)

Arquivo	Component_	FileName	FileSize	Versão	Idioma	Atributos	Sequência
MyAppFile	ProductComponent	PUASAMP1.EXE\|PUASample1.exe	81920			0	1

Os valores a serem salvos no registro podem ser especificados no campo Value da tabela Registry como uma cadeia de caracteres Formatada. Use o identificador de arquivo definido no campo File da tabela File e a convenção [#filekey] do tipo Formatado a fim de especificar o valor padrão para a chave do registro Caminhos do Aplicativo. A ação INSTALL de nível superior executa as ações na tabela InstallExecuteSequence. Depois que as ações CostInitialize, FileCost e InstallFinalize nessa tabela forem concluídas, o Windows Installer substituirá a subcadeia de caracteres formatada [#MyAppFile] na tabela Registry pelo caminho completo para o arquivo de aplicativo.

O exemplo define uma propriedade personalizada, RegRoot, para conter o local da chave raiz e usa uma ação personalizada para redefinir o valor da propriedade se o usuário escolher uma instalação em cada computador. Use a propriedade personalizada RegRoot em qualquer valor de cadeia de caracteres formatada que referencie o local raiz. Na tabela Property, o pacote PUASample.msi define a propriedade personalizada e define o valor de RegRoot como HKCU. Isso inicializa o valor da propriedade para o contexto de instalação de cada usuário, o contexto padrão recomendado para pacotes de dupla finalidade.

Tabela Property (parcial)

Propriedade	Valor
RegRoot	HKCU

Na tabela CustomAction, o pacote define uma ação personalizada chamada Set_RegRoot_HKLM. O valor no campo Type identifica isso como uma ação personalizada padrão Custom Action Type 51. O significado dos campos Source e Target na tabela CustomAction depende do tipo de ação personalizada. Para obter mais informações sobre os tipos padrão de ações personalizadas, confira Tipos de ação personalizada. O campo Source da ação personalizada Set_RegRoot_HKLM especifica o valor da propriedade RegRoot. Se o instalador executar a ação personalizada Set_RegRoot_HKLM, o valor da propriedade RegRoot será definido como HKLM.

Tabela CustomAction (parcial)

Ação	Tipo	Fonte	Destino
Set_RegRoot_HKLM	51	[RegRoot]	HKLM

A ação INSTALL de nível superior executa as ações na tabela InstallExecuteSequence, na sequência especificada no campo Sequence dessa tabela. O valor criado no campo Sequence para a ação personalizada Set_RegRoot_HKLM (1501) especifica que essa ação personalizada será executada após a ação InstallInitialize (1500) e antes da ação ProcessComponents (1600). Essa sequência faz com que o registro da ação personalizada Set_RegRoot_HKLM seja avaliado no momento da instalação. Para obter mais informações sobre a sequência recomendada de ações na tabela InstallExecuteSequence, confira o tópico InstallExecuteSequence sugerido. A sintaxe de instrução condicional criada no campo Condition especifica que a ação Set_RegRoot_HKLM seja executada somente se o valor da propriedade ALLUSERS for avaliado como 1 no momento da instalação. Um valor de propriedade ALLUSERS de 1 especifica uma instalação em cada computador.

Tabela InstallExecuteSequence (parcial)

Ação	Condição	Sequência
Set_RegRoot_HKLM	ALLUSERS=1	1501

Os registros a seguir na tabela Registry executam os registros se o componente ProductComponent estiver instalado. O valor -1 no campo Raiz é obrigatório para executar o registro em HKEY_LOCAL_MACHINE para uma instalação em cada usuário e em HKEY_CURRENT_USER para uma instalação em cada usuário. O registro com uma cadeia de caracteres vazia no campo Registry adiciona uma subchave para o aplicativo na chave do Registro AppPaths e define o valor "(Default)" como o caminho completo do arquivo executável do aplicativo. O registro MyAppPathAlias mapeia o arquivo executável para um alias de aplicativo e permite que o aplicativo seja iniciado se o usuário digitar o alias "puapct" em um prompt de linha de comando. O registro MyAppPathRegistration mapeia o nome do arquivo executável para o caminho completo do arquivo.

Registro	Root	Chave	Valor	Componente
	-1	Software\Microsoft\MyAppPathRegistrationLocation	[RegRoot]\Software\Microsoft\Windows\CurrentVersion\App Paths\PUAPCT.exe	ProductComponent
MyAppPathAlias	-1	Software\Microsoft\Windows\CurrentVersion\App Paths\PUAPCT.exe	[#MyAppFile]	ProductComponent
MyAppPathRegistration	-1	Software\Microsoft\Windows\CurrentVersion\App Paths\PUASample1.exe	[#MyAppFile]	ProductComponent

Registro de Cancelamento de Reprodução Automática

O PUASample.msi executa registros que permitem ao usuário do aplicativo impedir que a Reprodução Automática de Hardware seja iniciada para dispositivos selecionados. Para obter informações sobre como registrar um manipulador a fim de cancelar a reprodução automática em resposta a um evento, confira o tópico Preparando hardware e software para uso com reprodução automática na seção extensibilidade do shell do Guia do Desenvolvedor do Shell. O registro a seguir registra o manipulador especificado no campo Name quando o componente ProductComponent é instalado. O valor -1 no campo Root é necessário para especificar ao Windows Installer que o registro deve ser redirecionado para um local que depende do contexto de instalação.

Tabela Registry

Registro	Root	Chave	Nome	Valor	Componente
MyAutoplayCancelRegistration	-1	SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\AutoplayHandlers\CancelAutoplay\CLSID	66A32FE6-229D-427b-A608-D273F40C034C		ProductComponent

Registro do Manipulador de Visualização

O PUASample.msi executa registros necessários para instalar um manipulador de visualização que permite uma visualização somente leitura de arquivos .pua sem iniciar o aplicativo. Para obter informações sobre como registrar manipuladores de visualização, confira o tópico Registrando manipuladores de visualização na seção extensibilidade do shell do Guia do Desenvolvedor do Shell. Os registros a seguir na tabela Registry registram o manipulador quando o componente ProductComponent é instalado. O valor -1 no campo Root é necessário para especificar ao Windows Installer que o registro deve ser redirecionado para um local que depende do contexto de instalação.