Mage.exe (generování manifestu a nástroj pro úpravy)

Článek
01/30/2024

Nástroj pro generování a úpravy manifestu (Mage.exe) je nástroj příkazového řádku, který podporuje vytváření a úpravy manifestů aplikací a nasazení. Jako nástroj příkazového řádku je možné Mage.exe spouštět z dávkových skriptů i jiných aplikací založených na Windows, včetně ASP.NET aplikací.

Místo Mage.exe můžete použít také MageUI.exe, grafickou aplikaci. Další informace najdete v tématu MageUI.exe (generování manifestu a nástroj pro úpravy, grafický klient).

Tento nástroj je automaticky nainstalován se sadou Visual Studio. Ke spuštění nástroje použijte Visual Studio Developer Command Prompt nebo Visual Studio Developer PowerShell.

Součástí sady Visual Studio jsou dvě verze Mage.exe a MageUI.exe . Pokud chcete zobrazit informace o verzi, spusťte MageUI.exe, vyberte Nápověda a vyberte O aplikaci. Tato dokumentace popisuje verzi 4.0.x.x Mage.exe a MageUI.exe.

Syntaxe

Mage [commands] [commandOptions]

Parametry

Následující tabulka uvádí příkazy podporované Mage.exe. Další informace omožnostch

Příkaz	Popis
-cc, ClearApplicationCache	Odstraní všechny aplikace fungující pouze v režimu online z mezipaměti stažených aplikací.
-n, -NewfileType [newOptions]	Vytvoří nový soubor daného typu. Platné typy: - `Deployment`: Vytvoří nový manifest nasazení. - `Application`: Vytvoří nový manifest aplikace. Nezadáte-li s tímto příkazem žádné další parametry, bude vytvořen soubor odpovídajícího typu s odpovídajícími výchozími značkami a hodnotami atributů. Pomocí možnosti -ToFile (viz následující tabulka) zadejte název souboru a cestu k novému souboru. Pomocí možnosti -FromDirectory (viz následující tabulka) vytvořte manifest aplikace se všemi sestaveními pro aplikaci přidanou do <oddílu závislosti> manifestu.
-u, -Update[filePath] [updateOptions]	Provede jednu nebo více změn souboru manifestu. Typ upravovaného souboru není třeba zadávat. Nástroj Mage.exe soubor zkontroluje sadou heuristik a určí, zda jde o manifest nasazení nebo manifest aplikace. Pokud jste už soubor podepsali certifikátem, -Update odebere blok podpisu klíče. Důvodem je skutečnost, že podpis klíče obsahuje hodnotu hash souboru, která je úpravou souboru zneplatněna. Pomocí možnosti -ToFile (viz následující tabulka) zadejte nový název souboru a cestu místo přepsání existujícího souboru.
-s, -Sign`[signOptions]`	Použije k podpisu souboru pár klíčů nebo certifikát X509. Podpisy jsou do souboru vloženy jako prvky jazyka XML. Při podepisování manifestu, který určuje hodnotu -TimestampUri , musíte být připojeni k internetu.
-ver, -Verify[manifest-filename]	Ověří, jestli je manifest správně podepsaný. Nelze kombinovat s jinými příkazy. K dispozici v rozhraní .NET Framework 4.7 a novějších verzích.
-h, -?, -Help[verbose]	Popíše všechny dostupné příkazy a jejich možnosti. Zadejte `verbose` , abyste získali podrobnou nápovědu.

Možnosti příkazu New a Update

V následující tabulce jsou uvedeny možnosti podporované příkazy -New a -Update příkazy:

Možnosti	Výchozí hodnota	Platí pro	Popis
-a, -Algorithm	sha1RSA	Manifesty aplikací. Manifesty nasazení.	Určí algoritmus, jímž budou generovány přehledy závislostí. Hodnotou musí být „sha256RSA“ nebo „sha1RSA“. Použijte s možností „-Update“. Při použití možnosti „-Sign“ je tato možnost ignorována.
-appc, -AppCodeBase`manifestReference`		Manifesty nasazení.	Vloží odkaz na adresu URL nebo cestu k souboru do souboru manifestu aplikace. Touto hodnotou musí být úplná cesta k manifestu aplikace.
-appm, -AppManifest`manifestPath`		Manifesty nasazení.	Vloží do manifestu nasazení odkaz na manifest aplikace tohoto nasazení. Soubor označený `manifestPath` musí existovat nebo Mage.exe zobrazí chybu. Pokud soubor odkazovaný `manifestPath` není manifestem aplikace, Mage.exe vydá chybu.
-cf, -CertFile`filePath`		Všechny typy souborů.	Určuje umístění digitálního certifikátu X509 pro podepsání manifestu nebo souboru licence. Tuto možnost lze použít společně s možností -Password , pokud certifikát vyžaduje heslo pro soubory PFX (Personal Information Exchange). Počínaje rozhraním .NET Framework 4.7 je vyžadována kombinace možností -CryptoProvider a -KeyContainer , pokud soubor neobsahuje privátní klíč. Počínaje rozhraním .NET Framework 4.6.2 Mage.exe manifesty se značkami CNG i certifikáty CAPI.
-ch, -CertHash`hashSignature`		Všechny typy souborů.	Hodnota hash digitálního certifikátu uloženého v úložišti osobních certifikátů klientského počítače. Ta odpovídá řetězci kryptografického otisku digitálního certifikátu zobrazeného v Konzole certifikátů systému Windows. `hashSignature` může být buď velká nebo malá, a lze je zadat buď jako jeden řetězec, nebo s každým oktetem kryptografického otisku odděleným mezerami a celým kryptografickým otiskem uzavřeným v uvozovkách.
-csp, -CryptoProvider`provider-name`		Všechny typy souborů.	Určuje název zprostředkovatele kryptografických služeb (CSP), který obsahuje kontejner privátního klíče. Tato možnost vyžaduje možnost -KeyContainer . Tato možnost je dostupná od rozhraní .NET Framework 4.7.
-fd, -FromDirectory`directoryPath`		Manifesty aplikací.	Naplní manifest aplikace popisy všech sestavení a souborů nalezených v `directoryPath`, včetně všech podadresářů, kde `directoryPath` je adresář obsahující aplikaci, kterou chcete nasadit. Pro každý soubor v adresáři Mage.exe rozhodne, zda je soubor sestavení nebo statický soubor. Pokud se jedná o sestavení, přidá `<dependency>` do aplikace značku a `installFrom` atribut s názvem sestavení, základem kódu a verzí. Pokud se jedná o statický soubor, přidá `<file>` značku. Mage.exe také použije jednoduchou sadu heuristik ke zjištění hlavního spustitelného souboru aplikace a označí ji jako vstupní bod aplikace ClickOnce v manifestu. Mage.exe soubor nikdy automaticky neoznačí jako "datový" soubor. To je zapotřebí provést ručně. Další informace naleznete v tématu Postupy: Zahrnutí datového souboru do aplikace ClickOnce. Mage.exe také vygeneruje hodnotu hash pro každý soubor na základě jeho velikosti. Technologie ClickOnce těmito hodnotami hash zajišťuje, že se soubory nasazení nikdo od vytvoření manifestu nemanipuloval. Pokud se některý ze souborů v nasazení změní, můžete spustit Mage.exe pomocí příkazu -Update a možnosti -FromDirectory a aktualizovat hodnoty hash a verze sestavení všech odkazovaných souborů. -FromDirectory bude obsahovat všechny soubory ve všech podadresářích nalezených v rámci `directoryPath`. Pokud použijete -FromDirectory s příkazem -Update , Mage.exe odebere všechny soubory v manifestu aplikace, které již v adresáři neexistují.
-if, -IconFile`filePath`		Manifesty aplikací.	Určí úplnou cestu k souboru ikony .ICO. Tato ikona se zobrazuje vedle názvu aplikace v nabídce Start a v jejím záznamu v ovládacím panelu Přidat nebo odebrat programy. Není-li zadána žádná ikona, je použita ikona výchozí.
-ip, -IncludeProviderURL`url`	true	Manifesty nasazení.	Určuje, jestli manifest nasazení obsahuje hodnotu umístění aktualizace nastavenou parametrem -ProviderURL.
-i, -Install`willInstall`	true	Manifesty nasazení.	Označuje, zda by aplikace ClickOnce měla být nainstalována na místní počítač nebo spuštěna z webu. Instalace aplikace dává této aplikaci stav v nabídce Start systému Windows. Platnými hodnotami jsou „true“ nebo „t“ a „false“ nebo „f“. Pokud zadáte možnost -MinVersion a uživatel má nainstalovanou verzi menší než -MinVersion , vynutí instalaci aplikace bez ohledu na hodnotu, kterou předáte -Install. Tuto možnost nelze použít s možností -BrowserHosted . Pokus zadat obě možnosti pro stejný manifest vyústí v chybu.
-kc, -KeyContainer`name`		Všechny typy souborů.	Určuje kontejner klíčů, který obsahuje název privátního klíče. Tato možnost vyžaduje možnost CryptoProvider . Tato možnost je dostupná od rozhraní .NET Framework 4.7.
-mv, -MinVersion`[version]`	Verze uvedená v manifestu nasazení ClickOnce, jak je určeno příznakem -Version .	Manifesty nasazení.	Minimální verze aplikace, kterou uživatel může spustit. Tento příznak učiní pojmenovanou verzi aplikace požadovanou aktualizací. Vydáte-li verzi produktu s aktualizací proti narušující změně nebo závažné bezpečnostní chybě, lze pomocí tohoto příznaku určit, že aktualizace musí být nainstalována a že uživatel nemůže nadále používat dřívější verze. `version` má stejnou sémantiku jako argument příznaku -Version .
-n, -Name`nameString`	Nasadit	Všechny typy souborů.	Název použitý pro identifikaci aplikace. ClickOnce použije tento název k identifikaci aplikace v nabídce Start (pokud je aplikace nakonfigurována tak, aby se nainstalovala) a v dialogových oknech Zvýšení oprávnění. Poznámka: Pokud aktualizujete existující manifest a nezadáte název vydavatele pomocí této možnosti, Mage.exe aktualizuje manifest názvem organizace definovaným v počítači. Chcete-li použít jiný název, použijte tuto možnost a zadejte požadovaný název vydavatele.
-pwd, -Password`passwd`		Všechny typy souborů.	Heslo použité pro podepsání manifestu digitálním certifikátem. Musí být použit ve spojení s parametrem -CertFile .
-p, procesor`processorValue`	Msil	Manifesty aplikací. Manifesty nasazení.	Architektura mikroprocesoru, na níž bude distribuce spouštěna. Tato hodnota je vyžadována, pokud připravujete jednu nebo více instalací, jejichž sestavení byla předkompilována pro určitý mikroprocesor. Platné hodnoty zahrnují `msil`, `x86`, `ia64`a `amd64`. `msil` je microsoft intermediate language, což znamená, že všechna sestavení jsou nezávislá na platformě a modul CLR (Common Language Runtime) je bude při prvním spuštění aplikace zkompilovat za běhu.
-pu,-ProviderURL`url`		Manifesty nasazení.	Určuje adresu URL, na které technologie ClickOnce vyhledá aktualizace aplikace.
-pub, -Publisher`publisherName`		Manifesty aplikací. Manifesty nasazení.	Přidá název vydavatele do prvku popisu v manifestu nasazení nebo manifestu aplikace. Při použití v manifestu aplikace musí být parametr -UseManifestForTrust zadán také s hodnotou "true" nebo "t"; jinak tento parametr vyvolá chybu.
-s, -SupportURL`url`		Manifesty aplikací. Manifesty nasazení.	Určí odkaz, který se pro aplikaci ClickOnce objeví v ovládacím panelu Přidat nebo odebrat programy.
-ti, -TimestampUri`uri`		Manifesty aplikací. Manifesty nasazení.	Adresa URL služby vytváření digitálního časového razítka. Vytvoření časového razítka v manifestu umožňuje vyhnout se nutnosti znovu manifesty podepsat, pokud by digitální certifikát vypršel ještě před nasazením další verze aplikace. Další informace naleznete v tématu Členové programu kořenového certifikátu systému Windows.
-t, -ToFile`filePath`	-Nwe: – Nasazení: deploy.application – Aplikace: application.exe.manifest -Aktualizace: - Vstupní soubor.	Všechny typy souborů.	Určí výstupní cestu vytvořeného nebo upraveného souboru. Pokud -ToFile není zadán při použití -New, výstup se zapíše do aktuálního pracovního adresáře. Pokud -ToFile není zadán při použití -Update, Mage.exe zapíše soubor zpět do vstupního souboru.
-tr, -TrustLevel`level`	Dle zóny, v níž se adresa URL aplikace nachází.	Manifesty aplikací.	Úroveň důvěryhodnosti, která bude aplikacím udělena na klientských počítačích. Mezi hodnoty patří „Internet“, „Intranet“ a „FullTrust“.
-um, -UseManifestForTrust`willUseForTrust`	False	Manifesty aplikací.	Určí, zda bude při spuštění aplikace na klientském počítači použit pro rozhodování o důvěryhodnosti digitální podpis manifestu aplikace. Hodnota „true“ nebo „t“ určí, že pro rozhodnutí o důvěryhodnosti bude použit manifest aplikace. Hodnota „false“ nebo „f“ určí, že bude použit podpis manifestu nasazení.
-v, -Version`versionNumber`	1.0.0.0	Manifesty aplikací. Manifesty nasazení.	Verze nasazení. Argument musí být platným řetězcem verze ve formátu N.N.N.N, kde N je 32bitové celé číslo bez znaménka.
-wpf, -WPFBrowserApp`isWPFApp`	false (nepravda)	Manifesty aplikací. Manifesty nasazení.	Tento příznak použijte pouze v případě, že aplikace je aplikace Windows Presentation Foundation (WPF), která bude hostována v prohlížeči a není samostatný spustitelný soubor. Platnými hodnotami jsou „true“ nebo „t“ a „false“ nebo „f“. Pro manifesty aplikace vloží `hostInBrowser` atribut pod `entryPoint` prvek manifestu aplikace. Pro manifesty nasazení nastaví `install` atribut elementu `deployment` na false a uloží manifest nasazení s příponou .xbap. Zadání tohoto argumentu spolu s argumentem -Install způsobí chybu, protože aplikace hostovaná v prohlížeči nemůže být nainstalovaná offline aplikace.

Možnosti příkazu podepsat

V následující tabulce jsou uvedeny možnosti podporované příkazem -Sign , které platí pro všechny typy souborů.

Možnosti	Popis
-cf, -CertFile`filePath`	Určí umístění digitálního certifikátu pro podpis manifestu. Tuto možnost lze použít společně s možností -Password , pokud certifikát vyžaduje heslo pro soubory PFX (Personal Information Exchange). Počínaje rozhraním .NET Framework 4.7 je vyžadována kombinace možností -CryptoProvider a -KeyContainer , pokud soubor neobsahuje privátní klíč. Počínaje rozhraním .NET Framework 4.6.2 Mage.exe manifesty se značkami CNG i certifikáty CAPI.
-ch, -CertHash`hashSignature`	Hodnota hash digitálního certifikátu uloženého v úložišti osobních certifikátů klientského počítače. Ta odpovídá vlastnosti kryptografického otisku digitálního certifikátu zobrazeného v Konzole certifikátů systému Windows. `hashSignature` může být buď velká nebo malá, a lze je zadat buď jako jeden řetězec, nebo s každou oktetou kryptografického otisku odděleného mezerami a celým kryptografickým otiskem uzavřeným v uvozovkách.
-csp, -CryptoProvider`provider-name`	Určuje název zprostředkovatele kryptografických služeb (CSP), který obsahuje kontejner privátního klíče. Tato možnost vyžaduje možnost -KeyContainer . Tato možnost je dostupná od rozhraní .NET Framework 4.7.
-kc, -KeyContainer`name`	Určuje kontejner klíčů, který obsahuje název privátního klíče. Tato možnost vyžaduje možnost CryptoProvider . Tato možnost je dostupná od rozhraní .NET Framework 4.7.
-pwd, -Password`passwd`	Heslo použité pro podepsání manifestu digitálním certifikátem. Musí být použit ve spojení s parametrem -CertFile .
-t, -ToFile`filePath`	Určí výstupní cestu vytvořeného nebo upraveného souboru.

Poznámky

Všechny argumenty Mage.exe nerozlišují malá a velká písmena. Příkazy a možnosti mohou mít předponu pomlčky (-) nebo lomítka (/).

Všechny argumenty použité s příkazem -Sign je možné kdykoli použít i s příkazy -New nebo -Update . Následující příkazy jsou ekvivalentní.

mage -Sign c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx
mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx

Poznámka:

Od rozhraní .NET Framework verze 4.6.2 se podporují také certifikáty CNG.

Podpis by měl být poslední provedený úkol, protože podepsaný dokument používá hodnotu hash souboru pro ověření, zda je podpis pro dokument platný. Provedete-li v podepsaném souboru nějaké změny, je zapotřebí soubor znovu podepsat. Pokud podepíšete dokument, který byl dříve podepsaný, Mage.exe nahradí starý podpis novým podpisem.

Když použijete možnost -AppManifest k naplnění manifestu nasazení, Mage.exe předpokládá, že manifest aplikace se bude nacházet ve stejném adresáři jako manifest nasazení v podadresáři pojmenovaném po aktuální verzi nasazení a nakonfiguruje manifest nasazení odpovídajícím způsobem. Pokud se manifest aplikace bude nacházet jinde, nastavte alternativní umístění pomocí možnosti -AppCodeBase .

Před nasazením aplikace musí být manifesty nasazení a aplikace podepsány. Pokyny k podepisování manifestů najdete v tématu Přehled nasazení důvěryhodných aplikací.

Možnost -TrustLevel pro manifesty aplikace popisuje nastavení oprávnění, které aplikace vyžaduje ke spuštění v klientském počítači. Ve výchozím nastavení se aplikacím přiřadí úroveň důvěryhodnosti na základě zóny , ve které se nachází jejich adresa URL. Aplikace nasazené přes podnikovou síť jsou obecně umístěny do zóny Intranet, zatímco aplikace nasazené přes internet jsou umístěny do zóny Internet. Obě bezpečnostní zóny omezují přístup aplikace k místním prostředkům, přičemž zóna Intranet je méně restriktivní než zóna Internet. Zóna FullTrust dává aplikacím plný přístup k místním prostředkům počítače. Pokud použijete možnost -TrustLevel k umístění aplikace do této zóny, komponenta Správce důvěryhodnosti modulu CLR vyzve uživatele k rozhodnutí, zda chce udělit tuto vyšší úroveň důvěryhodnosti. Nasazujete-li aplikace přes podnikovou síť, lze úroveň důvěryhodnosti aplikace zvýšit bez dotazování uživatele pomocí technologie Trusted Application Deployment.

Manifesty aplikací také podporují vlastní oddíly trust. To pomáhá aplikacím podřídit se zásadě bezpečnosti požadovat nejmenší možná oprávnění, protože manifest lze nakonfigurovat tak, aby požadoval pouze specifická oprávnění potřebná ke spuštění aplikace. Mage.exe přímo nepodporuje přidání vlastního oddílu důvěryhodnosti. Můžete ho přidat pomocí textového editoru, analyzátoru XML nebo grafického nástroje MageUI.exe. Další informace o tom, jak pomocí MageUI.exe přidat vlastní oddíly důvěryhodnosti, najdete v tématu MageUI.exe (generování a úpravy manifestu, grafický klient).

Visual Studio 2017 obsahuje verzi 4.6.1 Mage.exe. Manifesty vytvořené s touto verzí Mage.exe cílové rozhraní .NET Framework 4. Pokud chcete cílit na starší verze rozhraní .NET Framework, použijte starší verzi Mage.exe.

Když přidáte nebo odeberete sestavení z existujícího manifestu nebo znovu podepíšete existující manifest, Mage.exe neaktualizuje manifest tak, aby cílil na rozhraní .NET Framework 4.

V následujících tabulkách jsou uvedené tyto funkce a omezení:

Verze manifestu	Operace	Mage v2.0	Mage v4.0
Manifest pro aplikace určené pro rozhraní .NET Framework verze 2.0 nebo 3.x	Otevření	OK	OK
	Close (Zavřít)	OK	OK
	Uložení	OK	OK
	Znovu podepsat	OK	OK
	Nová	OK	Nepodporováno
	Aktualizovat (viz níže)	OK	OK
Manifest pro aplikace cílené na rozhraní .NET Framework verze 4	Otevření	OK	OK
	Close (Zavřít)	OK	OK
	Uložení	OK	OK
	Znovu podepsat	OK	OK
	Nová	Nepodporováno	OK
	Aktualizovat (viz níže)	Nepodporováno	OK

Verze manifestu	Podrobnosti o operaci Aktualizovat	Mage v2.0	Mage v4.0
Manifest pro aplikace určené pro rozhraní .NET Framework verze 2.0 nebo 3.x	Upravit sestavení	OK	OK
	Přidat sestavení	OK	OK
	Odstranit sestavení	OK	OK
Manifest pro aplikace cílené na rozhraní .NET Framework verze 4	Upravit sestavení	Nepodporováno	OK
	Přidat sestavení	Nepodporováno	OK
	Odstranit sestavení	Nepodporováno	OK

Mage.exe vytvoří nové manifesty, které cílí na profil klienta rozhraní .NET Framework 4. Aplikace ClickOnce, které cílí na profil klienta rozhraní .NET Framework 4, mohou běžet v profilu klienta rozhraní .NET Framework 4 i v plné verzi rozhraní .NET Framework 4. Pokud vaše aplikace cílí na plnou verzi rozhraní .NET Framework 4 a nemůže spustit v profilu klienta rozhraní .NET Framework 4, odeberte prvek klienta <framework> pomocí textového editoru a znovu podepište manifest.

Následuje ukázkový <framework> prvek, který cílí na profil klienta rozhraní .NET Framework 4:

<framework targetVersion="4.0" profile="client" supportedRuntime="4.0.20506" />

Příklady

Následující příklad otevře uživatelské rozhraní mage (MageUI.exe).

mage

Následující příklady vytvoří výchozí manifest nasazení a manifest aplikace. Tyto soubory jsou vytvořeny v aktuálním pracovním adresáři a pojmenovány deploy.application a application.exe.manifest.

mage -New Deployment
mage -New Application

Následující příklad vytvoří manifest aplikace naplněný všemi sestaveními a soubory prostředků z aktuálního adresáře.

mage -New Application -FromDirectory . -Version 1.0.0.0

Následující příklad navazuje na předchozí příklad zadáním názvu nasazení a cílového mikroprocesoru. Také určuje adresu URL, na které má technologie ClickOnce hledat aktualizace.

mage -New Application -FromDirectory . -Name "Hello, World! Application" -Version 1.0.0.0 -Processor "x86" -ProviderUrl http://internalserver/HelloWorld/

Následující příklad ukazuje, jak vytvořit dvojici manifestů pro nasazení aplikace WPF, která bude hostována v prohlížeči.

mage -New Application -FromDirectory . -Version 1.0.0.0 -WPFBrowserApp true
mage -New Deployment -AppManifest 1.0.0.0\application.manifest -WPFBrowserApp true

Následující příklad vytvoří manifest aplikace naplněný všemi sestaveními a soubory prostředků z aktuálního adresáře a znaménka.

mage -New Application -FromDirectory . -Version 1.0.0.0 -KeyContainer keypair.snk -CryptoProvider "Microsoft Enhanced Cryptographic Provider v1.0"

Následující příklad aktualizuje manifest sestavení informacemi z manifestu aplikace a nastaví základ kódu pro umístění manifestu aplikace.

mage -Update HelloWorld.deploy -AppManifest 1.0.0.0\application.manifest -AppCodeBase http://internalserver/HelloWorld.deploy

Následující příklad upraví manifest nasazení tak, aby byla vynucena aktualizace verze, kterou má uživatel nainstalovánu.

mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -MinVersion 1.1.0.0

Následující příklad dává manifestu nasazení pokyn k načtení manifestu aplikace z jiného adresáře.

mage -Update HelloWorld.deploy -AppCodeBase http://anotherserver/HelloWorld/1.1.0.0/

Následující příklad podepíše existující manifest nasazení pomocí digitálního certifikátu v aktuálním pracovním adresáři.

mage -Sign deploy.application -CertFile cert.pfx -Password <passwd>

Následující příklad podepíše existující manifest nasazení pomocí digitálního certifikátu a privátního klíče v aktuálním pracovním adresáři.

mage -Sign deploy.application -CertFile cert.pfx -KeyContainer keyfile.snk -CryptoProvider "Microsoft Enhanced Cryptographic Provider v1.0"