Mage.exe (manifestgenererings- och redigeringsverktyg)
Manifestgenererings- och redigeringsverktyget (Mage.exe) är ett kommandoradsverktyg som stöder skapande och redigering av program- och distributionsmanifest. Som kommandoradsverktyg kan Mage.exe köras från både batchskript och andra Windows-baserade program, inklusive ASP.NET program.
Du kan också använda MageUI.exe, ett grafiskt program, i stället för Mage.exe. Mer information finns i MageUI.exe (manifestgenererings- och redigeringsverktyg, grafisk klient).
Det här verktyget installeras automatiskt med Visual Studio. Om du vill köra verktyget använder du Visual Studio Developer Command Prompt eller Visual Studio Developer PowerShell.
Två versioner av Mage.exe och MageUI.exe ingår i Visual Studio. Om du vill se versionsinformation kör du MageUI.exe, väljer Hjälp och väljer Om. Den här dokumentationen beskriver version 4.0.x.x av Mage.exe och MageUI.exe.
Syntax
Mage [commands] [commandOptions]
Parametrar
I följande tabell visas kommandon som stöds av Mage.exe. Mer information om de alternativ som stöds av dessa kommandon finns i Nytt och Uppdatera kommandoalternativ och Kommandoalternativ för Signera.
| Kommando | beskrivning |
|---|---|
| -cc, ClearApplicationCache | Rensar den nedladdade programcachen för alla program som endast är online. |
| -n, -New fileType [newOptions] | Skapar en ny fil av den angivna typen. Giltiga typer är: - Deployment: Skapar ett nytt distributionsmanifest.- Application: Skapar ett nytt programmanifest.Om du inte anger några ytterligare parametrar med det här kommandot skapas en fil av lämplig typ med lämpliga standardtaggar och attributvärden. Använd alternativet -ToFile (se i följande tabell) för att ange filnamnet och sökvägen till den nya filen. Använd alternativet -FromDirectory (se i följande tabell) för att skapa ett programmanifest med alla sammansättningar för ett program som lagts till i <beroendeavsnittet> i manifestet. |
| -u, -Update [filePath] [updateOptions] | Gör en eller flera ändringar i en manifestfil. Du behöver inte ange vilken typ av fil du redigerar. Mage.exe undersöker filen med hjälp av en uppsättning heuristik och avgör om det är ett distributionsmanifest eller ett programmanifest. Om du redan har signerat en fil med ett certifikat tar -Update bort nyckelsignaturblocket. Det beror på att nyckelsignaturen innehåller en hash för filen och om du ändrar filen blir hashen ogiltig. Använd alternativet -ToFile (se i följande tabell) för att ange ett nytt filnamn och sökväg i stället för att skriva över den befintliga filen. |
-s, -Sign [signOptions] |
Använder ett nyckelpar eller X509-certifikat för att signera en fil. Signaturer infogas som XML-element i filerna. Du måste vara ansluten till Internet när du signerar ett manifest som anger värdet -TimestampUri . |
| -ver, -Verify [manifest-filename] | Verifierar att manifestet är korrekt signerat. Det går inte att kombinera med andra kommandon. Finns i .NET Framework 4.7 och senare versioner. |
| -h, -?, -Hjälp [utförlig] | Beskriver alla tillgängliga kommandon och deras alternativ. Ange verbose för att få detaljerad hjälp. |
Nya kommandoalternativ och uppdateringsalternativ
I följande tabell visas de alternativ som stöds av kommandona -New och -Update :
| Alternativ | Standardvärde | Gäller för | beskrivning |
|---|---|---|---|
| -a, -Algorithm | sha1RSA | Programmanifest. Distributionsmanifest. |
Anger den algoritm som beroendesammandrag ska genereras med. Värdet måste vara "sha256RSA" eller "sha1RSA. Använd med alternativet "-Update". Det här alternativet ignoreras när du använder alternativet "-Sign" |
-appc, -AppCodeBase manifestReference |
Distributionsmanifest. | Infogar en URL- eller filsökvägsreferens till programmanifestfilen. Det här värdet måste vara den fullständiga sökvägen till programmanifestet. | |
-appm, -AppManifest manifestPath |
Distributionsmanifest. | Infogar en referens till en distributions programmanifest i dess distributionsmanifest. Filen som anges av manifestPath måste finnas, annars kommer Mage.exe att utfärda ett fel. Om filen som refereras av manifestPath inte är ett programmanifest kommer Mage.exe att utfärda ett fel. |
|
-cf, -CertFile filePath |
Alla filtyper. | Anger platsen för ett digitalt X509-certifikat för signering av ett manifest eller en licensfil. Det här alternativet kan användas tillsammans med alternativet -Password om certifikatet kräver ett lösenord för PFX-filer (Personal Information Exchange). Från och med .NET Framework 4.7 krävs en kombination av alternativen -CryptoProvider och -KeyContainer om filen inte innehåller en privat nyckel. Från och med .NET Framework 4.6.2 Mage.exe teckenmanifest med CNG samt CAPI-certifikat. |
|
-ch, -CertHash hashSignature |
Alla filtyper. | Hashen för ett digitalt certifikat som lagras i det personliga certifikatarkivet på klientdatorn. Detta motsvarar tumavtryckssträngen för ett digitalt certifikat som visas i Windows-certifikatkonsolen.hashSignature kan vara antingen versaler eller gemener och kan anges antingen som en enda sträng eller med varje oktett av tumavtrycket avgränsat med blanksteg och hela tumavtrycket omgivet av citattecken. |
|
-csp, -CryptoProvider provider-name |
Alla filtyper. | Anger namnet på en kryptografisk tjänstprovider (CSP) som innehåller containern för privat nyckel. Det här alternativet kräver alternativet -KeyContainer . Det här alternativet är tillgängligt från och med .NET Framework 4.7. |
|
-fd, -FromDirectory directoryPath |
Programmanifest. | Fyller i programmanifestet med beskrivningar av alla sammansättningar och filer som finns i directoryPath, inklusive alla underkataloger, där directoryPath är katalogen som innehåller det program som du vill distribuera. För varje fil i katalogen bestämmer Mage.exe om filen är en sammansättning eller en statisk fil. Om det är en sammansättning lägger den till en tagg och installFrom ett <dependency> attribut till programmet med sammansättningens namn, kodbas och version. Om det är en statisk fil lägger den till en <file> tagg. Mage.exe använder också en enkel uppsättning heuristik för att identifiera den huvudsakliga körbara filen för programmet och markerar den som ClickOnce-programmets startpunkt i manifestet.Mage.exe kommer aldrig automatiskt att markera en fil som en "data"-fil. Du måste göra detta manuellt. Mer information finns i Så här tar du med en datafil i ett ClickOnce-program. Mage.exe genererar också en hash för varje fil baserat på dess storlek. ClickOnce använder dessa hashvärden för att säkerställa att ingen har manipulerat distributionens filer sedan manifestet skapades. Om någon av filerna i distributionen ändras kan du köra Mage.exe med kommandot -Update och alternativet -FromDirectory , så uppdateras hash-filerna och sammansättningsversionerna för alla refererade filer. -FromDirectory inkluderar alla filer i alla underkataloger som finns i directoryPath.Om du använder -FromDirectory med kommandot -Update tar Mage.exe bort alla filer i programmanifestet som inte längre finns i katalogen. |
|
-if, -IconFile filePath |
Programmanifest. | Anger den fullständiga sökvägen till en . ICO-ikonfil. Den här ikonen visas bredvid programnamnet på Start-menyn och i posten Lägg till eller ta bort program. Om ingen ikon anges används en standardikon. | |
-ip, -IncludeProviderURL url |
true | Distributionsmanifest. | Anger om distributionsmanifestet innehåller det uppdateringsplatsvärde som angetts av -ProviderURL. |
-i, -Install willInstall |
true | Distributionsmanifest. | Anger om ClickOnce-programmet ska installeras på den lokala datorn eller om det ska köras från webben. Om du installerar ett program visas programmet på Start-menyn i Windows. Giltiga värden är "true" eller "t" och "false" eller "f". Om du anger alternativet -MinVersion och en användare har en version som är mindre än -MinVersion installerad, tvingar det programmet att installeras, oavsett vilket värde du skickar till -Install. Det här alternativet kan inte användas med alternativet -BrowserHosted . Om du försöker ange båda för samma manifest resulterar det i ett fel. |
-kc, -KeyContainer name |
Alla filtyper. | Anger den nyckelcontainer som innehåller namnet på den privata nyckeln. Det här alternativet kräver alternativet CryptoProvider . Det här alternativet är tillgängligt från och med .NET Framework 4.7. |
|
-mv, -MinVersion [version] |
Den version som anges i ClickOnce-distributionsmanifestet enligt flaggan -Version . | Distributionsmanifest. | Den lägsta versionen av det här programmet som en användare kan köra. Den här flaggan gör den namngivna versionen av ditt program till en nödvändig uppdatering. Om du släpper en version av produkten med en uppdatering till en icke-bakåtkompatibel ändring eller ett allvarligt säkerhetsfel kan du använda den här flaggan för att ange att uppdateringen måste installeras och att användaren inte kan fortsätta att köra tidigare versioner.version har samma semantik som argumentet till flaggan -Version . |
-n, -Name nameString |
Distribuera | Alla filtyper. | Namnet som används för att identifiera programmet. ClickOnce använder det här namnet för att identifiera programmet på Start-menyn (om programmet har konfigurerats för att installera sig självt) och i dialogrutan Behörighetshöjning. Obs! Om du uppdaterar ett befintligt manifest och inte anger något utgivarnamn med det här alternativet Mage.exe uppdaterar manifestet med organisationsnamnet som definierats på datorn. Om du vill använda ett annat namn måste du använda det här alternativet och ange önskat utgivarnamn. |
-pwd, -Password passwd |
Alla filtyper. | Lösenordet som används för att signera ett manifest med ett digitalt certifikat. Måste användas tillsammans med alternativet -CertFile . | |
-p, Processor processorValue |
Msil | Programmanifest. Distributionsmanifest. |
Den mikroprocessorarkitektur som distributionen ska köras på. Det här värdet krävs om du förbereder en eller flera installationer vars sammansättningar har förkompilerats för en specifik mikroprocessor. Giltiga värden är msil, x86, ia64och amd64. msil är Microsofts mellanliggande språk, vilket innebär att alla dina sammansättningar är plattformsoberoende, och CLR (Common Language Runtime) kompilerar dem just-in-time när programmet körs första gången. |
-pu, -ProviderURL url |
Distributionsmanifest. | Anger den URL som ClickOnce ska undersöka för programuppdateringar. | |
-pub, -Publisher publisherName |
Programmanifest. Distributionsmanifest. |
Lägger till utgivarnamnet i beskrivningselementet i antingen distributions- eller programmanifestet. När det används i ett programmanifest måste -UseManifestForTrust också anges med värdet "true" eller "t". Annars genererar den här parametern ett fel. | |
-s, -SupportURL url |
Programmanifest. Distributionsmanifest. |
Anger länken som visas i Lägg till eller ta bort program för ClickOnce-programmet. | |
-ti, -TimestampUri uri |
Programmanifest. Distributionsmanifest. |
URL:en för en digital tidsstämplingstjänst. Tidsstämpling av manifesten hindrar dig från att behöva signera om manifesten om ditt digitala certifikat upphör att gälla innan du distribuerar nästa version av programmet. Mer information finns i Windows-rotcertifikatprogrammedlemmar. | |
-t, -ToFile filePath |
-Ny: – Distribution: deploy.application - Program: application.exe.manifest -Uppdatera: – Indatafilen. |
Alla filtyper. | Anger utdatasökvägen för filen som har skapats eller ändrats. Om -ToFile inte anges när du använder -New skrivs utdata till den aktuella arbetskatalogen. Om -ToFile inte anges när du använder -Update skriver Mage.exe tillbaka filen till indatafilen. |
-tr, -TrustLevel level |
Baserat på zonen där programmets URL finns. | Programmanifest. | Förtroendenivån för att bevilja programmet på klientdatorer. Värdena är "Internet", "Intranet" och "FullTrust". |
-um, -UseManifestForTrust willUseForTrust |
Falsk | Programmanifest. | Anger om den digitala signaturen för programmanifestet ska användas för att fatta förtroendebeslut när programmet körs på klienten. Om du anger "true" eller "t" anges att programmanifestet ska användas för förtroendebeslut. Om du anger "false" eller "f" anges att signaturen för distributionsmanifestet ska användas. |
-v, -Version versionNumber |
1.0.0.0 | Programmanifest. Distributionsmanifest. |
Distributionens version. Argumentet måste vara en giltig versionssträng i formatet "N.N.N.N", där "N" är ett osignerat 32-bitars heltal. |
-wpf, -WPFBrowserApp isWPFApp |
falskt | Programmanifest. Distributionsmanifest. |
Använd endast den här flaggan om programmet är ett WPF-program (Windows Presentation Foundation) som ska finnas i en webbläsare och inte är en fristående körbar fil. Giltiga värden är "true" eller "t" och "false" eller "f". För programmanifest infogar hostInBrowser attributet under elementet entryPoint i programmanifestet.För distributionsmanifest anger install du attributet för elementet deployment till false och sparar distributionsmanifestet med ett .xbap-tillägg. Om du anger det här argumentet tillsammans med argumentet -Install genereras ett fel eftersom ett webbläsarbaserat program inte kan vara ett installerat offlineprogram. |
Kommandoalternativ för tecken
I följande tabell visas de alternativ som stöds av -Sign kommandot, som gäller för alla typer av filer.
| Alternativ | Description |
|---|---|
-cf, -CertFile filePath |
Anger platsen för ett digitalt certifikat för signering av ett manifest. Det här alternativet kan användas tillsammans med alternativet -Password om certifikatet kräver ett lösenord för PFX-filer (Personal Information Exchange). Från och med .NET Framework 4.7 krävs en kombination av alternativen -CryptoProvider och -KeyContainer om filen inte innehåller en privat nyckel. Från och med .NET Framework 4.6.2 Mage.exe teckenmanifest med CNG samt CAPI-certifikat. |
-ch, -CertHash hashSignature |
Hashen för ett digitalt certifikat som lagras i det personliga certifikatarkivet på klientdatorn. Detta motsvarar egenskapen Tumavtryck för ett digitalt certifikat som visas i Windows-certifikatkonsolen.hashSignature kan vara antingen versaler eller gemener och kan anges antingen som en enskild sträng eller med varje oktett av tumavtrycket avgränsat med blanksteg och hela tumavtrycket omgivet av citattecken. |
-csp, -CryptoProvider provider-name |
Anger namnet på en kryptografisk tjänstprovider (CSP) som innehåller containern för privat nyckel. Det här alternativet kräver alternativet -KeyContainer . Det här alternativet är tillgängligt från och med .NET Framework 4.7. |
-kc, -KeyContainer name |
Anger den nyckelcontainer som innehåller namnet på den privata nyckeln. Det här alternativet kräver alternativet CryptoProvider . Det här alternativet är tillgängligt från och med .NET Framework 4.7. |
-pwd, -Password passwd |
Lösenordet som används för att signera ett manifest med ett digitalt certifikat. Måste användas tillsammans med alternativet -CertFile . |
-t, -ToFile filePath |
Anger utdatasökvägen för filen som har skapats eller ändrats. |
Kommentarer
Alla argument för att Mage.exe är skiftlägesokänsliga. Kommandon och alternativ kan prefixeras med ett streck (-) eller ett snedstreck (/).
Alla argument som används med kommandot -Sign kan användas när som helst med kommandona -New eller -Update . Följande kommandon är likvärdiga.
mage -Sign c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx
mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx
Kommentar
Från och med .NET Framework version 4.6.2 stöds även CNG-certifikat.
Signering är den sista uppgiften du bör utföra eftersom ett signerat dokument använder en hash för filen för att verifiera att signaturen är giltig för dokumentet. Om du gör några ändringar i en signerad fil måste du signera den igen. Om du signerar ett dokument som tidigare signerats ersätter Mage.exe den gamla signaturen med den nya.
När du använder alternativet -AppManifest för att fylla i ett distributionsmanifest förutsätter Mage.exe att programmanifestet finns i samma katalog som distributionsmanifestet i en underkatalog med namnet efter den aktuella distributionsversionen och konfigurerar distributionsmanifestet på rätt sätt. Om programmanifestet finns någon annanstans använder du alternativet -AppCodeBase för att ange den alternativa platsen.
Distributions- och programmanifestet måste signeras innan du distribuerar programmet. Vägledning om signeringsmanifest finns i Översikt över distribution av betrodda program.
Alternativet -TrustLevel för programmanifest beskriver den behörighetsuppsättning som ett program kräver för att köras på klientdatorn. Som standard tilldelas program en förtroendenivå baserat på den zon där deras URL finns. Program som distribueras via ett företagsnätverk placeras vanligtvis i intranätzonen, medan de som distribueras via Internet placeras i Internetzonen. Båda säkerhetszonerna begränsar programmets åtkomst till lokala resurser, med zonen Intranät något mer tillåtande än Internetzonen. FullTrust-zonen ger program fullständig åtkomst till en dators lokala resurser. Om du använder alternativet -TrustLevel för att placera ett program i den här zonen uppmanas säkerhetshanterarens komponent i CLR användaren att bestämma om de vill bevilja den här högre förtroendenivån. Om du distribuerar programmet via ett företagsnätverk kan du använda Distribution av betrodda program för att höja programmets förtroendenivå utan att fråga användaren.
Programmanifest stöder även anpassade förtroendeavsnitt. Detta hjälper ditt program att följa säkerhetsprincipen för att begära minst behörighet, eftersom du kan konfigurera manifestet för att bara kräva de specifika behörigheter som programmet kräver för att kunna köras. Mage.exe har inte direkt stöd för att lägga till ett anpassat förtroendeavsnitt. Du kan lägga till en med hjälp av en textredigerare, en XML-parser eller det grafiska verktyget MageUI.exe. Mer information om hur du använder MageUI.exe för att lägga till anpassade förtroendeavsnitt finns i MageUI.exe (Verktyget för manifestgenerering och redigering, grafisk klient).
Visual Studio 2017 innehåller version 4.6.1 av Mage.exe. Manifest som skapats med den här versionen av Mage.exe .NET Framework 4 som mål. Om du vill rikta in dig på äldre versioner av .NET Framework använder du en tidigare version av Mage.exe.
När du lägger till eller tar bort sammansättningar från ett befintligt manifest eller signerar om ett befintligt manifest uppdaterar Mage.exe inte manifestet till målet .NET Framework 4.
Följande tabeller visar dessa funktioner och begränsningar:
| Manifestversion | Åtgärd | Mage v2.0 | Mage v4.0 |
|---|---|---|---|
| Manifest för program som riktar sig till version 2.0 eller 3.x av .NET Framework | Öppnats | OK | OK |
| Stäng | OK | OK | |
| Spara | OK | OK | |
| Signera igen | OK | OK | |
| Nytt | OK | Stöds inte | |
| Uppdatera (se nedan) | OK | OK | |
| Manifest för program som riktar sig till version 4 av .NET Framework | Öppnats | OK | OK |
| Stäng | OK | OK | |
| Spara | OK | OK | |
| Signera igen | OK | OK | |
| Nytt | Stöds inte | OK | |
| Uppdatera (se nedan) | Stöds inte | OK |
| Manifestversion | Information om uppdateringsåtgärd | Mage v2.0 | Mage v4.0 |
|---|---|---|---|
| Manifest för program som riktar sig till version 2.0 eller 3.x av .NET Framework | Ändra en sammansättning | OK | OK |
| Lägga till en sammansättning | OK | OK | |
| Ta bort en sammansättning | OK | OK | |
| Manifest för program som riktar sig till version 4 av .NET Framework | Ändra en sammansättning | Stöds inte | OK |
| Lägga till en sammansättning | Stöds inte | OK | |
| Ta bort en sammansättning | Stöds inte | OK |
Mage.exe skapar nya manifest som riktar sig mot .NET Framework 4-klientprofilen. ClickOnce-program som riktar sig mot .NET Framework 4-klientprofilen kan köras på både .NET Framework 4-klientprofilen och den fullständiga versionen av .NET Framework 4. Om ditt program riktar sig mot den fullständiga versionen av .NET Framework 4 och inte kan köras på .NET Framework 4-klientprofilen tar du bort klientelementet <framework> med hjälp av en textredigerare och signerar manifestet igen.
Följande är ett exempelelement <framework> som riktar sig till .NET Framework 4-klientprofilen:
<framework targetVersion="4.0" profile="client" supportedRuntime="4.0.20506" />
Exempel
I följande exempel öppnas användargränssnittet för Mage (MageUI.exe).
mage
I följande exempel skapas ett standarddistributionsmanifest och programmanifest. Alla dessa filer skapas i den aktuella arbetskatalogen och heter deploy.application respektive application.exe.manifest.
mage -New Deployment
mage -New Application
I följande exempel skapas ett programmanifest fyllt med alla sammansättningar och resursfiler från den aktuella katalogen.
mage -New Application -FromDirectory . -Version 1.0.0.0
I följande exempel fortsätter föregående exempel genom att ange distributionsnamnet och målmikroprocessorn. Den anger också en URL som ClickOnce ska söka efter uppdateringar mot.
mage -New Application -FromDirectory . -Name "Hello, World! Application" -Version 1.0.0.0 -Processor "x86" -ProviderUrl http://internalserver/HelloWorld/
I följande exempel visas hur du skapar ett par manifest för att distribuera ett WPF-program som ska finnas i en webbläsare.
mage -New Application -FromDirectory . -Version 1.0.0.0 -WPFBrowserApp true
mage -New Deployment -AppManifest 1.0.0.0\application.manifest -WPFBrowserApp true
I följande exempel skapas ett programmanifest fyllt med alla sammansättningar och resursfiler från den aktuella katalogen och tecknen.
mage -New Application -FromDirectory . -Version 1.0.0.0 -KeyContainer keypair.snk -CryptoProvider "Microsoft Enhanced Cryptographic Provider v1.0"
I följande exempel uppdateras ett distributionsmanifest med information från ett programmanifest och anger kodbasen för platsen för programmanifestet.
mage -Update HelloWorld.deploy -AppManifest 1.0.0.0\application.manifest -AppCodeBase http://internalserver/HelloWorld.deploy
I följande exempel redigeras distributionsmanifestet för att tvinga fram en uppdatering av användarens installerade version.
mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -MinVersion 1.1.0.0
I följande exempel uppmanas distributionsmanifestet att hämta programmanifestet från en annan katalog.
mage -Update HelloWorld.deploy -AppCodeBase http://anotherserver/HelloWorld/1.1.0.0/
I följande exempel signeras ett befintligt distributionsmanifest med ett digitalt certifikat i den aktuella arbetskatalogen.
mage -Sign deploy.application -CertFile cert.pfx -Password <passwd>
I följande exempel signeras ett befintligt distributionsmanifest med hjälp av ett digitalt certifikat och en privat nyckel i den aktuella arbetskatalogen.
mage -Sign deploy.application -CertFile cert.pfx -KeyContainer keyfile.snk -CryptoProvider "Microsoft Enhanced Cryptographic Provider v1.0"
