Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
A Ferramenta de Geração e Edição de Manifesto (Mage.exe) é uma ferramenta de linha de comando que dá suporte à criação e edição de manifestos de aplicativo e implantação. Como uma ferramenta de linha de comando, Mage.exe podem ser executados em scripts em lotes e em 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).
Essa ferramenta é instalada automaticamente com o Visual Studio. Para executar a ferramenta, use o Prompt de Comando do Desenvolvedor do Visual Studio ou o PowerShell do Desenvolvedor do Visual Studio.
Duas versões de Mage.exe e MageUI.exe estão incluídas no Visual Studio. Para ver as informações de versão, execute MageUI.exe, selecione Ajuda e selecione Sobre. Esta documentação descreve a versão 4.0.x.x de Mage.exe e MageUI.exe.
Sintaxe
Mage [commands] [commandOptions]
Parâmetros
A tabela a seguir mostra os comandos compatíveis comMage.exe. Para obter mais informações sobre as opções compatíveis com esses comandos, consulte as opções de comando Nova e Atualização eopções de comando Assinar.
| Comando | Descrição |
|---|---|
| -cc, ClearApplicationCache | Limpa o cache do aplicativo baixado somente de todos os aplicativos online. |
| -n, -Novotipo de arquivo [novasopções] | Cria um novo arquivo do tipo indicado. 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 parâmetros adicionais com esse comando, ele criará um arquivo do tipo apropriado, com as marcas padrão adequadas e os valores de atributo. Use a opção -ToFile (consulte na tabela a seguir) para especificar o nome do arquivo e o caminho do novo arquivo. Use a opção -FromDirectory (consulte na tabela a seguir) para criar um manifesto do 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. Você não precisa especificar o tipo de arquivo que está editando. Mage.exe examinará o arquivo usando um conjunto de heurística e determinará se ele é 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 é porque a assinatura-chave contém um hash do arquivo e a modificação do arquivo invalida o hash. Use a opção -ToFile (consulte na 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 um certificado X509 para assinar um arquivo. As assinaturas são inseridas como elementos XML nos arquivos. Você deve estar conectado à Internet ao assinar um manifesto que especifica um valor -TimestampUri . |
| -ver, -Verify[nome-do-arquivo-manifesto] | Verifica se o manifesto está assinado corretamente. Não pode ser combinada com outros comandos. Disponível no .NET Framework 4.7 e versões posteriores. |
| -h, -?, -Help[detalhado] | Descreve todos os comandos disponíveis e suas opções. Especifique verbose para obter ajuda detalhada. |
Opções de comando novas e atualizadas
A tabela a seguir mostra as opções compatíveis com os comandos -New e -Update:
| Opções | Valor padrão | Aplica-se A | Descrição |
|---|---|---|---|
| -a, -Algoritmo | sha1RSA | Manifestos de aplicativo. 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". |
-appc, -AppCodeBasemanifestReference |
Manifestos de implantação. | Insere uma referência de URL ou de caminho do arquivo no arquivo de manifesto do aplicativo. Esse valor deve ser o caminho completo do manifesto de aplicativo. | |
-appm, -AppManifestmanifestPath |
Manifestos de implantação. | Insere uma referência para o manifesto de aplicativo de uma implantação no manifesto de implantação. O arquivo indicado deve manifestPath 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, -CertFilefilePath |
Todos os tipos de arquivo. | Especifica o local de um certificado digital X509 para assinar um manifesto ou arquivo de licença. Essa opção pode ser usada em conjunto com a opção -Password se o certificado exigir uma senha para arquivos PFX (Troca de Informações Pessoais). 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 assina manifestos com CNG, bem como certificados CAPI. |
|
-ch, -CertHashhashSignature |
Todos os tipos de arquivo. | O hash de um certificado digital armazenado no repositório de certificados pessoais do computador cliente. Isso corresponde à cadeia de caracteres Impressão Digital de um certificado digital exibido no Windows Certificates Console.hashSignature pode ter maiúsculas ou minúsculas e 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, -Provedor de criptografiaprovider-name |
Todos os tipos de arquivo. | Especifica o nome de um provedor de serviços de criptografia (CSP) que contém o contêiner de chave privada. Essa opção requer a opção -KeyContainer . Essa opção está disponível a partir do .NET Framework 4.7. |
|
-fd, -FromDirectorydirectoryPath |
Manifestos de aplicativo. | Popula o manifesto do aplicativo com descrições de todos os assemblies e arquivos encontrados em directoryPath, inclusive todos os subdiretórios, em que 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 adicionará uma marca <dependency> e um atributo installFrom ao aplicativo com o nome do assembly, a base de código e a versão. Se for um arquivo estático, ele adicionará uma marca <file>.
Mage.exe também usará um conjunto simples de heurísticas para detectar o executável principal para o 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. ClickOnce usa esses hashes para garantir que ninguém adultere os arquivos de implantação desde a criação do manifesto. Se qualquer um dos arquivos em sua implantação mudar, você poderá executar Mage.exe com o comando -Update e a opção -FromDirectory , e ele atualizará as versões hashes e assembly de todos os arquivos referenciados. -FromDirectory incluirá todos os arquivos em todos os subdiretórios encontrados dentro 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. |
|
-if, -ArquivoÍconefilePath |
Manifestos de aplicativo. | Especifica o caminho completo para um arquivo de ícone .ICO. Esse ícone é exibido ao lado do nome do aplicativo no menu Iniciar e na entrada Adicionar ou Remover Programas. Se nenhum ícone for fornecido, será usado um ícone padrão. | |
-ip, -IncludeProviderURLurl |
verdadeiro | Manifestos de implantação. | Indica se o manifesto de implantação inclui o valor do local de atualização definido por -ProviderURL. |
-i, -InstalarwillInstall |
verdadeiro | Manifestos de implantação. | Indica se o aplicativo ClickOnce deve ou não ser instalado no computador local, ou se o deve ser executado na Web. A instalação de um aplicativo fornece 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á o aplicativo a ser instalado, independentemente do valor que você passar para -Install. Essa opção não pode ser usada com a opção -BrowserHosted . A tentativa de especificar ambos para o mesmo manifesto resultará em um erro. |
-kc, -KeyContainername |
Todos os tipos de arquivo. | Especifica o contêiner de chave que contém o nome da chave privada. Essa opção requer a opção CryptoProvider . Essa opção está disponível a partir do .NET Framework 4.7. |
|
-mv, -MinVersion[version] |
A versão listada no manifesto de implantação do ClickOnce, conforme especificado pelo sinalizador -Version . | Manifestos de implantação. | A versão mínima desse aplicativo que um usuário pode executar. Esse sinalizador torna a versão nomeada do aplicativo uma atualização obrigatória. Se liberar uma versão do produto com uma atualização para uma alteração importante ou uma falha de segurança crítica, você poderá usar esse sinalizador para especificar se essa atualização deve ser instalada e se o usuário não pode continuar executando versões anteriores.version tem a mesma semântica que o argumento para o sinalizador -Version . |
-n, -NomenameString |
Implantar | Todos os tipos de arquivo. | O nome usado para identificar o aplicativo. O 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, não se esqueça de usar essa opção e especificar o nome do editor desejado. |
-pwd, -Senhapasswd |
Todos os tipos de arquivo. | A senha que é usada na assinatura de um manifesto com um certificado digital. Deve ser usado em conjunto com a opção -CertFile . | |
-p, ProcessadorprocessorValue |
Msil | Manifestos de aplicativo. Manifestos de implantação. |
A arquitetura do microprocessador em que essa distribuição será executada. Esse valor será obrigató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, ia64 e amd64.
msil é a Microsoft Intermediate Language, o que significa que todos os assemblies independem da plataforma e o CLR (Common Language Runtime) os compilará just-in-time quando o aplicativo for executado pela primeira vez. |
-pu,-URL do provedorurl |
Manifestos de implantação. | Especifica a URL que o ClickOnce examinará em busca de atualizações de aplicativo. | |
-pub, -EditorapublisherName |
Manifestos de aplicativo. Manifestos de implantação. |
Adiciona o nome do editor ao elemento de descrição do manifesto de implantação ou de aplicativo. Quando usado em um manifesto do aplicativo, -UseManifestForTrust também deve ser especificado com um valor "true" ou "t"; caso contrário, esse parâmetro gerará um erro. | |
-s, -URL de suporteurl |
Manifestos de aplicativo. Manifestos de implantação. |
Especifica o link exibido em Adicionar ou Remover Programas do aplicativo ClickOnce. | |
-ti, -TimestampUriuri |
Manifestos de aplicativo. Manifestos de implantação. |
A URL de um serviço de carimbo de data/hora digital. O carimbo de data/hora dos manifestos evita que você precise assinar novamente os manifestos, caso o certificado digital expire antes de implantar a próxima versão do aplicativo. Para obter mais informações, consulte os membros do programa de certificado raiz do Windows. | |
-t, -ToFilefilePath |
− Novo: – Implantação: deploy.application – Aplicativo: application.exe.manifest − Atualização: – O arquivo de entrada. |
Todos os tipos de arquivo. | 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, -TrustLevellevel |
Com base na zona em que reside a URL do aplicativo. | Manifestos de aplicativo. | O nível de confiança a ser concedido ao aplicativo em computadores cliente. Entre os valores estão "Internet", "Intranet" e "FullTrust". |
-um, -UseManifestForTrustwillUseForTrust |
Falso | Manifestos de aplicativo. | Especifica se a assinatura digital do manifesto de aplicativo será usada para na tomada de decisões de confiança quando o aplicativo é executado no cliente. A especificação de "true" ou "t" indica que o manifesto do aplicativo será usado em decisões de confiança. A especificação de "false" ou "f" indica que a assinatura do manifesto de implantação será usada. |
-v, -VersãoversionNumber |
1.0.0.0 | Manifestos de aplicativo. 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", em que "N" é um inteiro sem sinal de 32 bits. |
-wpf, -WPFBrowserAppisWPFApp |
falso | Manifestos de aplicativo. Manifestos de implantação. |
Só use esse sinalizador se o aplicativo for um aplicativo do WPF (Windows Presentation Foundation) que será hospedado dentro de um navegador, e não um executável autônomo. Os valores válidos são "true" ou "t" e "false" ou "f". Para manifestos de aplicativo, insere o atributo hostInBrowser no elemento entryPoint do manifesto de aplicativo.Para manifestos de implantação, define o atributo install no elemento deployment como falso e salva o manifesto de implantação com uma extensão .xbap. Especificar esse argumento junto com o argumento -Install produz um erro, pois um aplicativo hospedado pelo navegador não pode ser um aplicativo offline instalado. |
Opções do comando de entrada
A tabela a seguir mostra as opções compatíveis com o comando -Sign, que se aplicam a todos os tipos de arquivos.
| Opções | Descrição |
|---|---|
| -a, -Algoritmo | Especifica o algoritmo com o qual gerar resumos de dependência. O valor deve ser "sha256RSA". |
-cf, -CertFilefilePath |
Especifica o local de um certificado digital para assinar um manifesto. Essa opção pode ser usada em conjunto com a opção -Password se o certificado exigir uma senha para arquivos PFX (Troca de Informações Pessoais). 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 assina manifestos com CNG, bem como certificados CAPI. |
-ch, -CertHashhashSignature |
O hash de um certificado digital armazenado no repositório de certificados pessoais do computador cliente. Isso corresponde à propriedade Impressão Digital de um certificado digital exibido no Windows Certificates Console.hashSignature pode ter maiúsculas ou minúsculas e 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, -Provedor de criptografiaprovider-name |
Especifica o nome de um provedor de serviços de criptografia (CSP) que contém o contêiner de chave privada. Essa opção requer a opção -KeyContainer . Essa opção está disponível a partir do .NET Framework 4.7. |
-kc, -KeyContainername |
Especifica o contêiner de chave que contém o nome da chave privada. Essa opção requer a opção CryptoProvider . Essa opção está disponível a partir do .NET Framework 4.7. |
-pwd, -Senhapasswd |
A senha que é usada na assinatura de um manifesto com um certificado digital. Deve ser usado em conjunto com a opção -CertFile . |
-ti, -TimestampUriuri |
A URL de um serviço de carimbo de data/hora digital. O carimbo de data/hora dos manifestos impede que você precise assinar novamente os manifestos se o certificado digital expirar antes de implantar a próxima versão do aplicativo. |
-t, -ToFilefilePath |
Especifica o caminho de saída do arquivo que foi criado ou modificado. |
Comentários
Todos os argumentos para Mage.exe não diferenciam maiúsculas de minúsculas. Os comandos e as opções podem ser precedidos por um traço (-) ou uma barra (/).
Todos os argumentos usados com o comando -Sign também podem ser usados a qualquer momento com os comandos -New ou -Update . 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
Observação
A partir do .NET Framework versão 4.6.2, certificados CNG também têm suporte.
A assinatura é a última tarefa que você deve realizar, porque um documento assinado usa um hash do arquivo para verificar se a assinatura é válida para o documento. Se fizer alguma alteração em um arquivo assinado, você deverá assiná-lo novamente. Se você assinar um documento assinado anteriormente, Mage.exe substituirá a assinatura antiga pelo novo.
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 em um subdiretório nomeado após a versão de implantação atual e configurará seu manifesto de implantação adequadamente. Se o manifesto do aplicativo residir em outro lugar, use a opção -AppCodeBase para definir o local alternativo.
O manifesto de implantação e de aplicativo deverá ser assinado antes de você implantar o aplicativo. Para obter diretrizes 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 na qual reside a URL. Os aplicativos implantados em uma rede corporativa costumam ser colocados na zona Intranet, enquanto os implantados na Internet são colocados na zona Internet. Ambas as zonas de segurança impõem restrições sobre o acesso do aplicativo a recursos locais, com a zona Intranet um pouco mais permissiva do que a zona Internet. A zona FullTrust dá aos aplicativos acesso completo para 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 estiver implantando o aplicativo em uma rede corporativa, você poderá usar a Implantação do Aplicativo de Confiança para aumentar o nível de confiança do aplicativo sem perguntar ao usuário.
Os manifestos de aplicativo também dão suporte a seções de confiança personalizadas. Isso ajuda o aplicativo a obedecer o princípio de segurança de solicitar permissão mínima, porque é possível configurar o manifesto para exigir apenas essas permissões específicas que o aplicativo exige para execução. Mage.exe não dá suporte diretamente à 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. Manifestos criados com esta versão do .NET Framework 4 de destinoMage.exe . 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 dos aplicativos com a versão 2.0 ou 3.x do .NET Framework como destino | Abrir | OKEY | OKEY |
| Fechar | OKEY | OKEY | |
| Salvar | OKEY | OKEY | |
| Assinar Novamente | OKEY | OKEY | |
| Novo | OKEY | Sem suporte | |
| Atualizar (veja abaixo) | OKEY | OKEY | |
| Manifesto dos aplicativos com a versão 4 do .NET Framework como destino | Abrir | OKEY | OKEY |
| Fechar | OKEY | OKEY | |
| Salvar | OKEY | OKEY | |
| Assinar Novamente | OKEY | OKEY | |
| Novo | Sem suporte | OKEY | |
| Atualizar (veja abaixo) | Sem suporte | OKEY |
| Versão do manifesto | Detalhes da Operação de Atualização | Mago v2.0 | Mago v4.0 |
|---|---|---|---|
| Manifesto dos aplicativos com a versão 2.0 ou 3.x do .NET Framework como destino | Modificar um assembly | OKEY | OKEY |
| Adicionar um assembly | OKEY | OKEY | |
| Remover um assembly | OKEY | OKEY | |
| Manifesto dos aplicativos com a versão 4 do .NET Framework como destino | Modificar um assembly | Sem suporte | OKEY |
| Adicionar um assembly | Sem suporte | OKEY | |
| Remover um assembly | Sem suporte | OKEY |
Mage.exe cria novos manifestos direcionados ao perfil do cliente .NET Framework 4. Os aplicativos ClickOnce direcionados ao perfil de cliente .NET Framework 4 podem ser executados no perfil de cliente .NET Framework 4 e na versão completa do .NET Framework 4. Se o destino do aplicativo for a versão completa do .NET Framework 4 e não puder ser executado no perfil de cliente .NET Framework 4, remova o elemento <framework> do cliente usando um editor de texto e assine novamente o manifesto.
Veja a seguir um elemento de exemplo <framework> que tem como destino o perfil de cliente .NET Framework 4:
<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 o manifesto do aplicativo. Esses arquivos são todos criados no diretório de trabalho atual e chamados deploy.application e application.exe.manifest, respectivamente.
mage -New Deployment
mage -New Application
O exemplo a seguir cria um manifesto de aplicativo populado com todos os assemblies e arquivos de recurso 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 na 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 do 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 populado com todos os assemblies e arquivos de recurso do diretório atual e o assina.
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 do local do manifesto de 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 o 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"