Sdílet prostřednictvím


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

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, -New fileType [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, ia64a 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 -Nový:
– 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
Zavřít OK OK
Uložit 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
Zavřít OK OK
Uložit 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"

Viz také