Mage.exe (Ferramenta de Geração e Edição de Manifestos)
A Ferramenta de Geração e Edição de Manifestos (Mage.exe) é uma ferramenta de linha de comando que suporta a criação e edição de manifestos de aplicativo e implantação. Como uma ferramenta de linha de comando, Mage.exe pode ser executado a partir de scripts em lote e outros aplicativos baseados no Windows, incluindo aplicativos ASP.NET.
Você também pode usar MageUI.exe, um aplicativo gráfico, em vez de Mage.exe. Para obter mais informações, consulte MageUI.exe (Ferramenta de geração e edição de manifesto, cliente gráfico).
Esta ferramenta é instalada automaticamente com o Visual Studio. Para executar a ferramenta, use o Visual Studio Developer Command Prompt ou o Visual Studio Developer PowerShell.
Duas versões do Mage.exe e MageUI.exe estão incluídas no Visual Studio. Para ver informações sobre a versão, execute MageUI.exe, selecione Ajuda e selecione Sobre. Esta documentação descreve a versão 4.0.x.x do Mage.exe e MageUI.exe.
Sintaxe
Mage [commands] [commandOptions]
Parâmetros
A tabela a seguir mostra os comandos suportados pelo Mage.exe. Para obter mais informações sobre as opções suportadas por esses comandos, consulte Opções de comando Novo e Atualizar e Opções de comando Assinar.
| Comando | Description |
|---|---|
| -cc, ClearApplicationCache | Limpa o cache do aplicativo baixado de todos os aplicativos somente online. |
| -n, -New fileType [newOptions] | Cria um novo arquivo do tipo determinado. Os tipos válidos são: - Deployment: Cria um novo manifesto de implantação.- Application: Cria um novo manifesto do aplicativo.Se você não especificar nenhum parâmetro adicional com esse comando, ele criará um arquivo do tipo apropriado, com tags padrão e valores de atributo apropriados. Use a opção -ToFile (consulte a tabela a seguir) para especificar o nome do arquivo e o caminho do novo arquivo. Use a opção -FromDirectory (consulte a tabela a seguir) para criar um manifesto de aplicativo com todos os assemblies para um aplicativo adicionado à <seção de dependência> do manifesto. |
| -u, -Update [filePath] [updateOptions] | Faz uma ou mais alterações em um arquivo de manifesto. Não é necessário especificar o tipo de arquivo que está editando. Mage.exe examinará o arquivo usando um conjunto de heurísticas e determinará se é um manifesto de implantação ou um manifesto de aplicativo. Se você já assinou um arquivo com um certificado, -Update removerá o bloco de assinatura de chave. Isso ocorre porque a assinatura de chave contém um hash do arquivo, e modificar o arquivo torna o hash inválido. Use a opção -ToFile (consulte a tabela a seguir) para especificar um novo nome de arquivo e caminho em vez de substituir o arquivo existente. |
-s, -Sinal [signOptions] |
Usa um par de chaves ou certificado X509 para assinar um arquivo. As assinaturas são inseridas como elementos XML dentro dos arquivos. Você deve estar conectado à Internet ao assinar um manifesto que especifica um valor -TimestampUri . |
| -ver, -Verify [manifest-filename] | Verifica se o manifesto está assinado corretamente. Não pode ser combinado com outros comandos. Disponível no .NET Framework 4.7 e versões posteriores. |
| -h, -?, -Ajuda [verbose] | Descreve todos os comandos disponíveis e suas opções. Especifique verbose para obter ajuda detalhada. |
Opções de comando Novo e Atualizar
A tabela a seguir mostra as opções suportadas -New pelos comandos and -Update :
| Opções | Valor Predefinido | Aplica-se A | Description |
|---|---|---|---|
| -a, -Algoritmo | sha1RSA | Manifestos de aplicação. Manifestos de implantação. |
Especifica o algoritmo com o qual gerar resumos de dependência. O valor deve ser "sha256RSA" ou "sha1RSA. Use com a opção "-Update". Esta opção é ignorada ao usar a opção "-Sign" |
-appc, -AppCodeBase manifestReference |
Manifestos de implantação. | Insere uma referência de URL ou caminho de arquivo para o arquivo de manifesto do aplicativo. Esse valor deve ser o caminho completo para o manifesto do aplicativo. | |
-appm, -AppManifest manifestPath |
Manifestos de implantação. | Insere uma referência ao manifesto do aplicativo de uma implantação em seu manifesto de implantação. O arquivo indicado por manifestPath deve existir, ou Mage.exe emitirá um erro. Se o arquivo referenciado por manifestPath não for um manifesto do aplicativo, Mage.exe emitirá um erro. |
|
-cf, -CertFile filePath |
Todos os tipos de ficheiros. | Especifica o local de um certificado digital X509 para assinar um manifesto ou arquivo de licença. Esta opção pode ser usada em conjunto com a opção -Password se o certificado exigir uma senha para arquivos PFX (Personal Information Exchange). A partir do .NET Framework 4.7, se o arquivo não contiver uma chave privada, será necessária uma combinação das opções -CryptoProvider e -KeyContainer . A partir do .NET Framework 4.6.2, Mage.exe sinaliza manifestos com CNG, bem como certificados CAPI. |
|
-ch, -CertHash hashSignature |
Todos os tipos de ficheiros. | O hash de um certificado digital armazenado no armazenamento de certificados pessoais do computador cliente. Isso corresponde à cadeia de caracteres de impressão digital de um certificado digital exibido no Console de Certificados do Windows.hashSignature pode ser maiúscula ou minúscula e pode ser fornecido como uma única cadeia de caracteres ou com cada octeto da impressão digital separado por espaços e toda a impressão digital entre aspas. |
|
-csp, -CryptoProvider provider-name |
Todos os tipos de ficheiros. | Especifica o nome de um provedor de serviços de criptografia (CSP) que contém o contêiner de chave privada. Esta opção requer a opção -KeyContainer . Esta opção está disponível a partir do .NET Framework 4.7. |
|
-fd, -FromDirectory directoryPath |
Manifestos de aplicação. | Preenche o manifesto do aplicativo com descrições de todos os assemblies e arquivos encontrados no directoryPath, incluindo todos os subdiretórios, onde directoryPath é o diretório que contém o aplicativo que você deseja implantar. Para cada arquivo no diretório, Mage.exe decide se o arquivo é um assembly ou um arquivo estático. Se for um assembly, ele adiciona uma <dependency> tag e installFrom um atributo ao aplicativo com o nome, a base de código e a versão do assembly. Se for um arquivo estático, ele adiciona uma <file> tag. Mage.exe também usará um conjunto simples de heurísticas para detetar o executável principal do aplicativo e o marcará como o ponto de entrada do aplicativo ClickOnce no manifesto.Mage.exe nunca marcará automaticamente um arquivo como um arquivo de "dados". Você deve fazer isso manualmente. Para obter mais informações, consulte Como incluir um arquivo de dados em um aplicativo ClickOnce. Mage.exe também gera um hash para cada arquivo com base em seu tamanho. O ClickOnce usa esses hashes para garantir que ninguém tenha adulterado os arquivos da implantação desde que o manifesto foi criado. Se qualquer um dos arquivos em sua implantação mudar, você pode executar Mage.exe com o comando -Update e a opção -FromDirectory, e ele atualizará as versões de hashes e assembly de todos os arquivos referenciados. -FromDirectory incluirá todos os arquivos em todos os subdiretórios encontrados em directoryPath.Se você usar -FromDirectory com o comando -Update , Mage.exe removerá todos os arquivos no manifesto do aplicativo que não existem mais no diretório. |
|
-se, -IconFile filePath |
Manifestos de aplicação. | Especifica o caminho completo para um arquivo . Arquivo de ícone ICO. Esse ícone aparece ao lado do nome do aplicativo no menu Iniciar e na entrada Adicionar ou Remover Programas. Se nenhum ícone for fornecido, um ícone padrão será usado. | |
-ip, -IncludeProviderURL url |
verdadeiro | Manifestos de implantação. | Indica se o manifesto de implantação inclui o valor do local de atualização definido por -ProviderURL. |
-i, -Instalar willInstall |
verdadeiro | Manifestos de implantação. | Indica se o aplicativo ClickOnce deve ou não ser instalado no computador local ou se deve ser executado a partir da Web. A instalação de um aplicativo dá a esse aplicativo uma presença no menu Iniciar do Windows. Os valores válidos são "true" ou "t" e "false" ou "f". Se você especificar a opção -MinVersion e um usuário tiver uma versão menor que -MinVersion instalada, isso forçará a instalação do aplicativo, independentemente do valor que você passar para -Install. Esta opção não pode ser usada com a opção -BrowserHosted . Tentar especificar ambos para o mesmo manifesto resultará em um erro. |
-kc, -KeyContainer name |
Todos os tipos de ficheiros. | Especifica o contêiner de chave que contém o nome da chave privada. Esta opção requer a opção CryptoProvider . Esta opção está disponível a partir do .NET Framework 4.7. |
|
-mv, -MinVersion [version] |
A versão listada no manifesto de implantação ClickOnce conforme especificado pelo sinalizador -Version . | Manifestos de implantação. | A versão mínima deste aplicativo que um usuário pode executar. Esse sinalizador torna a versão nomeada do seu aplicativo uma atualização necessária. Se você lançar uma versão do seu produto com uma atualização para uma alteração de quebra ou uma falha crítica de segurança, poderá usar esse sinalizador para especificar que essa atualização deve ser instalada e que o usuário não pode continuar a executar versões anteriores.version tem a mesma semântica que o argumento para o sinalizador -Version . |
-n, -Nome nameString |
Implementar | Todos os tipos de ficheiros. | O nome usado para identificar o aplicativo. ClickOnce usará esse nome para identificar o aplicativo no menu Iniciar (se o aplicativo estiver configurado para se instalar) e nas caixas de diálogo Elevação de permissão. Nota: Se você estiver atualizando um manifesto existente e não especificar um nome de editor com essa opção, Mage.exe atualizará o manifesto com o nome da organização definido no computador. Para usar um nome diferente, certifique-se de usar essa opção e especifique o nome do editor desejado. |
-pwd, -Senha passwd |
Todos os tipos de ficheiros. | A senha usada para assinar um manifesto com um certificado digital. Deve ser usado em conjunto com a opção -CertFile . | |
-p, Processador processorValue |
Msil | Manifestos de aplicação. Manifestos de implantação. |
A arquitetura do microprocessador na qual essa distribuição será executada. Esse valor é necessário se você estiver preparando uma ou mais instalações cujos assemblies foram pré-compilados para um microprocessador específico. Os valores válidos incluem msil, x86, ia64e amd64. msil é a linguagem intermediária da Microsoft, o que significa que todos os assemblies são independentes da plataforma e o Common Language Runtime (CLR) irá compilá-los just-in-time quando seu aplicativo for executado pela primeira vez. |
-pu, -ProviderURL url |
Manifestos de implantação. | Especifica a URL que o ClickOnce examinará para atualizações do aplicativo. | |
-pub, -Editora publisherName |
Manifestos de aplicação. Manifestos de implantação. |
Adiciona o nome do editor ao elemento description do manifesto de implantação ou aplicativo. Quando usado em um manifesto de aplicativo, -UseManifestForTrust também deve ser especificado com um valor de "true" ou "t", caso contrário, esse parâmetro gerará um erro. | |
-s, -SupportURL url |
Manifestos de aplicação. Manifestos de implantação. |
Especifica o link que aparece em Adicionar ou remover programas para o aplicativo ClickOnce. | |
-ti, -TimestampUri uri |
Manifestos de aplicação. Manifestos de implantação. |
A URL de um serviço digital de carimbo de data/hora. O carimbo de data/hora dos manifestos evita que você tenha que assinar novamente os manifestos caso seu certificado digital expire antes de implantar a próxima versão do seu aplicativo. Para obter mais informações, consulte Membros do programa de certificado raiz do Windows. | |
-t, -ToFile filePath |
-Novo: - Implantação: deploy.application - Aplicação: application.exe.manifest - Atualização: - O arquivo de entrada. |
Todos os tipos de ficheiros. | Especifica o caminho de saída do arquivo que foi criado ou modificado. Se -ToFile não for fornecido quando você usar -New, a saída será gravada no diretório de trabalho atual. Se -ToFile não for fornecido quando você usar -Update, Mage.exe gravará o arquivo de volta no arquivo de entrada. |
-tr, -Nível de Confiança level |
Com base na zona em que a URL do aplicativo reside. | Manifestos de aplicação. | O nível de confiança para conceder o aplicativo em computadores cliente. Os valores incluem "Internet", "Intranet" e "FullTrust". |
-um, -UseManifestForTrust willUseForTrust |
False | Manifestos de aplicação. | Especifica se a assinatura digital do manifesto do aplicativo será usada para tomar decisões de confiança quando o aplicativo for executado no cliente. Especificar "true" ou "t" indica que o manifesto do aplicativo será usado para decisões de confiança. Especificar "false" ou "f" indica que a assinatura do manifesto de implantação será usada. |
-v, -Versão versionNumber |
1.0.0.0 | Manifestos de aplicação. Manifestos de implantação. |
A versão da implantação. O argumento deve ser uma cadeia de caracteres de versão válida do formato "N.N.N.N", ONDE "N" é um inteiro de 32 bits não assinado. |
-wpf, -WPFBrowserApp isWPFApp |
false | Manifestos de aplicação. Manifestos de implantação. |
Use esse sinalizador somente se o aplicativo for um aplicativo do Windows Presentation Foundation (WPF) que será hospedado dentro de um navegador e não for um executável autônomo. Os valores válidos são "true" ou "t" e "false" ou "f". Para manifestos de aplicativo, insere o hostInBrowser atributo sob o entryPoint elemento do manifesto do aplicativo.Para manifestos de implantação, define o install deployment atributo no elemento como false e salva o manifesto de implantação com uma extensão .xbap. Especificar esse argumento junto com o argumento -Install produz um erro, porque um aplicativo hospedado no navegador não pode ser um aplicativo offline instalado. |
Opções de comando Assinar
A tabela a seguir mostra as opções suportadas -Sign pelo comando, que se aplicam a todos os tipos de arquivos.
| Opções | Description |
|---|---|
-cf, -CertFile filePath |
Especifica o local de um certificado digital para assinar um manifesto. Esta opção pode ser usada em conjunto com a opção -Password se o certificado exigir uma senha para arquivos PFX (Personal Information Exchange). A partir do .NET Framework 4.7, se o arquivo não contiver uma chave privada, será necessária uma combinação das opções -CryptoProvider e -KeyContainer . A partir do .NET Framework 4.6.2, Mage.exe sinaliza manifestos com CNG, bem como certificados CAPI. |
-ch, -CertHash hashSignature |
O hash de um certificado digital armazenado no armazenamento de certificados pessoais do computador cliente. Isso corresponde à propriedade Thumbprint de um certificado digital exibido no Console de Certificados do Windows.hashSignature pode ser maiúscula ou minúscula, e pode ser fornecido como uma única string ou com cada octeto da impressão digital separado por espaços e toda a impressão digital entre aspas. |
-csp, -CryptoProvider provider-name |
Especifica o nome de um provedor de serviços de criptografia (CSP) que contém o contêiner de chave privada. Esta opção requer a opção -KeyContainer . Esta opção está disponível a partir do .NET Framework 4.7. |
-kc, -KeyContainer name |
Especifica o contêiner de chave que contém o nome da chave privada. Esta opção requer a opção CryptoProvider . Esta opção está disponível a partir do .NET Framework 4.7. |
-pwd, -Senha passwd |
A senha usada para assinar um manifesto com um certificado digital. Deve ser usado em conjunto com a opção -CertFile . |
-t, -ToFile filePath |
Especifica o caminho de saída do arquivo que foi criado ou modificado. |
Observações
Todos os argumentos a Mage.exe não diferenciam maiúsculas de minúsculas. Os comandos e opções podem ser prefixados com um traço (-) ou uma barra (/).
Todos os argumentos usados com o comando -Sign podem ser usados a qualquer momento com os comandos -New ou -Update também. Os comandos a seguir são equivalentes.
mage -Sign c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx
mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx
Nota
A partir do .NET Framework versão 4.6.2, os certificados CNG também são suportados.
A assinatura é a última tarefa que você deve executar, porque um documento assinado usa um hash do arquivo para verificar se a assinatura é válida para o documento. Se você fizer alterações em um arquivo assinado, deverá assiná-lo novamente. Se você assinar um documento que foi assinado anteriormente, Mage.exe substituirá a assinatura antiga pela nova.
Quando você usa a opção -AppManifest para preencher um manifesto de implantação, Mage.exe assumirá que o manifesto do aplicativo residirá no mesmo diretório que o manifesto de implantação dentro de um subdiretório nomeado após a versão de implantação atual e configurará o manifesto de implantação adequadamente. Se o manifesto do aplicativo residir em outro lugar, use a opção -AppCodeBase para definir o local alternativo.
A implantação e o manifesto do aplicativo devem ser assinados antes de implantar o aplicativo. Para obter orientação sobre como assinar manifestos, consulte Visão geral da implantação de aplicativos confiáveis.
A opção -TrustLevel para manifestos de aplicativo descreve o conjunto de permissões que um aplicativo requer para ser executado no computador cliente. Por padrão, os aplicativos recebem um nível de confiança com base na zona em que sua URL reside. Os aplicativos implantados em uma rede corporativa geralmente são colocados na zona da Intranet, enquanto os implantados pela Internet são colocados na zona da Internet. Ambas as zonas de segurança impõem restrições ao acesso do aplicativo aos recursos locais, com a zona da Intranet um pouco mais permissiva do que a zona da Internet. A zona FullTrust dá aos aplicativos acesso completo aos recursos locais de um computador. Se você usar a opção -TrustLevel para colocar um aplicativo nessa zona, o componente Gerenciador de Confiança do CLR solicitará que o usuário decida se deseja conceder esse nível mais alto de confiança. Se você estiver implantando seu aplicativo em uma rede corporativa, poderá usar a Implantação de Aplicativo Confiável para aumentar o nível de confiança do aplicativo sem avisar o usuário.
Os manifestos de aplicativos também oferecem suporte a seções de confiança personalizadas. Isso ajuda seu aplicativo a obedecer ao princípio de segurança de solicitar permissão mínima, pois você pode configurar o manifesto para exigir apenas as permissões específicas que o aplicativo requer para ser executado. Mage.exe não suporta diretamente a adição de uma seção de confiança personalizada. Você pode adicionar um usando um editor de texto, um analisador XML ou a ferramenta gráfica MageUI.exe. Para obter mais informações sobre como usar MageUI.exe para adicionar seções de confiança personalizadas, consulte MageUI.exe (Ferramenta de geração e edição de manifesto, cliente gráfico).
O Visual Studio 2017 inclui a versão 4.6.1 do Mage.exe. Os manifestos criados com esta versão do .NET Framework 4 de destino Mage.exe destino. Para direcionar versões mais antigas do .NET Framework, use uma versão anterior do Mage.exe.
Quando você adiciona ou remove assemblies de um manifesto existente ou assina novamente um manifesto existente, Mage.exe não atualiza o manifesto para o .NET Framework 4 de destino.
As tabelas a seguir mostram esses recursos e restrições:
| Versão do manifesto | Operação | Mago v2.0 | Mago v4.0 |
|---|---|---|---|
| Manifesto para aplicativos destinados à versão 2.0 ou 3.x do .NET Framework | Abertura | OK | OK |
| Fechar | OK | OK | |
| Guardar | OK | OK | |
| Assine novamente | OK | OK | |
| Novo | OK | Não suportado | |
| Atualização (veja abaixo) | OK | OK | |
| Manifesto para aplicativos destinados à versão 4 do .NET Framework | Abertura | OK | OK |
| Fechar | OK | OK | |
| Guardar | OK | OK | |
| Assine novamente | OK | OK | |
| Novo | Não suportado | OK | |
| Atualização (veja abaixo) | Não suportado | OK |
| Versão do manifesto | Atualizar detalhes da operação | Mago v2.0 | Mago v4.0 |
|---|---|---|---|
| Manifesto para aplicativos destinados à versão 2.0 ou 3.x do .NET Framework | Modificar um assembly | OK | OK |
| Adicionar um assembly | OK | OK | |
| Remover uma montagem | OK | OK | |
| Manifesto para aplicativos destinados à versão 4 do .NET Framework | Modificar um assembly | Não suportado | OK |
| Adicionar um assembly | Não suportado | OK | |
| Remover uma montagem | Não suportado | OK |
Mage.exe cria novos manifestos destinados ao .NET Framework 4 Client Profile. Os aplicativos ClickOnce destinados ao .NET Framework 4 Client Profile podem ser executados no .NET Framework 4 Client Profile e na versão completa do .NET Framework 4. Se o seu aplicativo tiver como alvo a versão completa do .NET Framework 4 e não puder ser executado no .NET Framework 4 Client Profile, remova o elemento client <framework> usando um editor de texto e assine novamente o manifesto.
A seguir está um elemento de exemplo <framework> que tem como alvo o .NET Framework 4 Client Profile:
<framework targetVersion="4.0" profile="client" supportedRuntime="4.0.20506" />
Exemplos
O exemplo a seguir abre a interface do usuário para Mage (MageUI.exe).
mage
Os exemplos a seguir criam um manifesto de implantação padrão e um manifesto do aplicativo. Esses arquivos são todos criados no diretório de trabalho atual e são chamados deploy.application e application.exe.manifest, respectivamente.
mage -New Deployment
mage -New Application
O exemplo a seguir cria um manifesto de aplicativo preenchido com todos os assemblies e arquivos de recursos do diretório atual.
mage -New Application -FromDirectory . -Version 1.0.0.0
O exemplo a seguir continua o exemplo anterior especificando o nome da implantação e o microprocessador de destino. Ele também especifica uma URL em relação à qual o ClickOnce deve verificar se há atualizações.
mage -New Application -FromDirectory . -Name "Hello, World! Application" -Version 1.0.0.0 -Processor "x86" -ProviderUrl http://internalserver/HelloWorld/
O exemplo a seguir demonstra como criar um par de manifestos para implantar um aplicativo WPF que será hospedado em um navegador.
mage -New Application -FromDirectory . -Version 1.0.0.0 -WPFBrowserApp true
mage -New Deployment -AppManifest 1.0.0.0\application.manifest -WPFBrowserApp true
O exemplo a seguir cria um manifesto de aplicativo preenchido com todos os assemblies e arquivos de recursos do diretório e sinais atuais.
mage -New Application -FromDirectory . -Version 1.0.0.0 -KeyContainer keypair.snk -CryptoProvider "Microsoft Enhanced Cryptographic Provider v1.0"
O exemplo a seguir atualiza um manifesto de implantação com informações de um manifesto de aplicativo e define a base de código para o local do manifesto do aplicativo.
mage -Update HelloWorld.deploy -AppManifest 1.0.0.0\application.manifest -AppCodeBase http://internalserver/HelloWorld.deploy
O exemplo a seguir edita o manifesto de implantação para forçar uma atualização da versão instalada do usuário.
mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -MinVersion 1.1.0.0
O exemplo a seguir informa ao manifesto de implantação para recuperar o manifesto do aplicativo de outro diretório.
mage -Update HelloWorld.deploy -AppCodeBase http://anotherserver/HelloWorld/1.1.0.0/
O exemplo a seguir assina um manifesto de implantação existente usando um certificado digital no diretório de trabalho atual.
mage -Sign deploy.application -CertFile cert.pfx -Password <passwd>
O exemplo a seguir assina um manifesto de implantação existente usando um certificado digital e uma chave privada no diretório de trabalho atual.
mage -Sign deploy.application -CertFile cert.pfx -KeyContainer keyfile.snk -CryptoProvider "Microsoft Enhanced Cryptographic Provider v1.0"
