Vágási beállítások

  • Cikk

A következő MSBuild tulajdonságok és elemek befolyásolják a levágott, önálló telepítések viselkedését. Néhány lehetőség említést tesz ILLink, amely a vágást megvalósító mögöttes eszköz neve. A mögöttes eszközről további információt a Trimmer dokumentációjában talál.

A vágást a PublishTrimmed .NET Core 3.0-ban vezettük be. A többi lehetőség csak a .NET 5-ös és újabb verzióiban érhető el.

Vágás engedélyezése

  • <PublishTrimmed>true</PublishTrimmed>

    A közzététel során engedélyezze a vágást. Ez a beállítás kikapcsolja a nem kompatibilis vágási funkciókat is, és lehetővé teszi a vágáselemzést a buildelés során. A .NET 8 és újabb alkalmazásokban ez a beállítás lehetővé teszi a konfigurációs kötést és a delegált forrásgenerátorok kérését is.

Feljegyzés

Ha a parancssorból engedélyezi a vágást, a hibakeresési élmény eltérő lesz, és további hibák léphetnek fel a végtermékben.

Helyezze ezt a beállítást a projektfájlba, és győződjön meg arról, hogy a beállítás nem csak dotnet publishaz adott időszakban dotnet buildérvényes.

Ez a beállítás alapértelmezés szerint lehetővé teszi az összes szerelvény vágását és vágását. A .NET 6-ban alapértelmezés szerint csak azokat a szerelvényeket vágták le, amelyek a vágást [AssemblyMetadata("IsTrimmable", "True")] engedélyezték. Az előző viselkedéshez a következővel <TrimMode>partial</TrimMode>térhet vissza: .

Ez a beállítás levágja a vágáshoz konfigurált szerelvényeket. A Microsoft.NET.Sdk .NET 6-ban ez magában foglalja a .NET futtatókörnyezeti szerelvényekhez tartozó szerelvényeket [AssemblyMetadata("IsTrimmable", "True")]is. A .NET 5-ben a netcoreapp futtatókörnyezeti csomagból származó szerelvények az MSBuild metaadatokon keresztüli <IsTrimmable> vágásra vannak konfigurálva. Más SDK-k eltérő alapértelmezett értékeket határozhatnak meg.

Ez a beállítás lehetővé teszi a Vágáskompatibilitási Roslyn-elemzőt , és letiltja a vágással nem kompatibilis funkciókat.

Részletesség vágása

TrimMode A tulajdonság használatával a vágás részletességét a következőre állíthatja: vagy partialfull. A konzolalkalmazások (és a .NET 8-tól kezdve a Webes SDK-alkalmazások) alapértelmezett beállítása a következő full:

<TrimMode>full</TrimMode>

Ha csak a vágást választó szerelvényeket szeretné levágni, állítsa a tulajdonságot a következőre partial:

<TrimMode>partial</TrimMode>

Ha a vágási módot partialmódosítja, az egyes szerelvényeket az MSBuild elem használatával <TrimmableAssembly> vághatja le.

<ItemGroup>
  <TrimmableAssembly Include="MyAssembly" />
</ItemGroup>

Ez egyenértékű a szerelvény létrehozásakor megadott beállítással [AssemblyMetadata("IsTrimmable", "True")] .

Az alábbi részletességi beállítások szabályozzák, hogy a rendszer milyen agresszíven nem használt IL-t vet el. Ez olyan tulajdonságként állítható be, amely hatással van az összes vágóbemeneti szerelvényekre, vagy metaadatokként egy adott szerelvényen, amely felülbírálja a tulajdonságbeállítást.

  • <TrimMode>link</TrimMode>

    Engedélyezze a tagszintű vágást, amely eltávolítja a nem használt tagokat a típusok közül. Ez az alapértelmezett a .NET 6+-ban.

  • <TrimMode>copyused</TrimMode>

    Szerelvényszintű vágás engedélyezése, amely a teljes szerelvényt megtartja, ha annak bármely részét használják (statikusan érthető módon).

A metaadatokat tartalmazó <IsTrimmable>true</IsTrimmable> szerelvények, de explicit módon nem TrimMode használják a globális TrimMode. Az alapértelmezett TrimMode érték a linkMicrosoft.NET.Sdk .NET 6+ és copyused a korábbi verziókban van.

További szerelvények vágása

A .NET 6+- PublishTrimmed ban a szerelvényeket a következő szerelvényszintű attribútummal vágja le:

[AssemblyMetadata("IsTrimmable", "True")]

A keretrendszertárak rendelkeznek ezzel az attribútummal. A .NET 6+-ban az attribútum nélküli kódtárak kivágását is választhatja, a szerelvényt név szerint (bővítmény .dll nélkül) megadva.

Az egyes szerelvények vágási beállításai

A levágott alkalmazások közzétételekor az SDK kiszámít egy ItemGroup olyan nevet ManagedAssemblyToLink , amely a vágáshoz feldolgozandó fájlok készletét jelöli. ManagedAssemblyToLink lehetnek olyan metaadatok, amelyek a szerelvényenkénti vágási viselkedést vezérli. A metaadatok beállításához hozzon létre egy célértéket, amely a beépített PrepareForILLink cél előtt fut. Az alábbi példa bemutatja, hogyan engedélyezheti a vágást.MyAssembly

<Target Name="ConfigureTrimming"
        BeforeTargets="PrepareForILLink">
  <ItemGroup>
    <ManagedAssemblyToLink Condition="'%(Filename)' == 'MyAssembly'">
      <IsTrimmable>true</IsTrimmable>
    </ManagedAssemblyToLink>
  </ItemGroup>
</Target>

Ezzel a céllal felülbírálhatja a kódtár szerzője által megadott vágási viselkedést is, ha <IsTrimmable>false</IsTrimmable> beállít egy szerelvényt a következővel [AssemblyMetadata("IsTrimmable", "True"]): .

Ne vegyen fel vagy távolítson el elemeket, ManagedAssemblyToLinkmert az SDK a közzététel során kiszámítja ezt a készletet, és várhatóan nem változik. A támogatott metaadatok a következőek:

  • <IsTrimmable>true</IsTrimmable>

    Annak szabályozása, hogy az adott szerelvény levágva van-e.

  • <TrimMode>copyused</TrimMode> vagy <TrimMode>link</TrimMode>

    A szerelvény vágási részletességének szabályozása. Ez a metaadatok elsőbbséget élveznek a globális TrimMode. A TrimMode szerelvény beállítása azt jelenti, hogy <IsTrimmable>true</IsTrimmable>.

  • <TrimmerSingleWarn>True</TrimmerSingleWarn>

    Szabályozhatja, hogy egyetlen figyelmeztetés jelenjen-e meg ehhez a szerelvényhez.

Gyökérszerelvények

Ha egy szerelvény nincs levágva, a rendszer "gyökerezettnek" tekinti, ami azt jelenti, hogy a szerelvény és az összes statikusan értelmezett függősége megmarad. A további szerelvények név szerint "gyökereznek" (bővítmény .dll nélkül):

<ItemGroup>
  <TrimmerRootAssembly Include="MyAssembly" />
</ItemGroup>

Gyökérleírók

Az elemzési gyökerek megadásának másik módja egy olyan XML-fájl használata, amely a vágóleíró formátumát használja. Ez lehetővé teszi, hogy egy teljes szerelvény helyett konkrét tagokat gyökereztetsen.

<ItemGroup>
  <TrimmerRootDescriptor Include="MyRoots.xml" />
</ItemGroup>

Előfordulhat például, MyRoots.xml hogy egy adott metódust gyökereztet, amelyet az alkalmazás dinamikusan elér:

<linker>
  <assembly fullname="MyAssembly">
    <type fullname="MyAssembly.MyClass">
      <method name="DynamicallyAccessedMethod" />
    </type>
  </assembly>
</linker>

Elemzési figyelmeztetések

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    Vágáselemzési figyelmeztetések engedélyezése.

A vágás eltávolítja a statikusan nem elérhető IL-t. A tükrözést vagy más dinamikus függőségeket létrehozó mintákat használó alkalmazások vágással megszakadhatnak. Az ilyen mintákra való figyelmeztetéshez állítsa be <SuppressTrimAnalysisWarnings> a következőt false: . Ez a beállítás a teljes alkalmazásra vonatkozó figyelmeztetéseket jelenít meg, beleértve a saját kódját, a kódtár kódját és a keretrendszer kódját.

Roslyn-elemző

A .NET 6+-ban való beállítás PublishTrimmed lehetővé teszi a Roslyn-elemző használatát is, amely korlátozott számú elemzési figyelmeztetést jelenít meg. Az elemzőt a következőtől függetlenül PublishTrimmedis engedélyezheti vagy tilthatja le.

  • <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

    Engedélyezze a Roslyn-elemzőt a vágáselemzési figyelmeztetések egy részhalmazához.

Figyelmeztetések mellőzése

Az egyes figyelmeztető kódok letilthatók az eszközlánc által betartott szokásos MSBuild tulajdonságok használatával, beleértve NoWarna , WarningsAsErrors, WarningsNotAsErrorsés TreatWarningsAsErrors. Van egy további lehetőség, amely egymástól függetlenül szabályozza az ILLink hibaalapú viselkedését:

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    Ne kezelje az ILLink-figyelmeztetéseket hibákként. Ez hasznos lehet, ha elkerüli, hogy a vágáselemzési figyelmeztetéseket hibákká alakítsa a fordítói figyelmeztetések globális hibaként való kezelésekor.

Részletes figyelmeztetések megjelenítése

A .NET 6+-ban a vágáselemzés legfeljebb egy figyelmeztetést eredményez minden egyes szerelvényhez, amely egy PackageReferenceadott szerelvényből származik, ami azt jelzi, hogy a szerelvény belső elemei nem kompatibilisek a vágással. Az egyes szerelvényekre vonatkozó figyelmeztetéseket is megjelenítheti:

  • <TrimmerSingleWarn>false</TrimmerSingleWarn>

    Az összes részletes figyelmeztetés megjelenítése ahelyett, hogy szerelvényenként egyetlen figyelmeztetésre összecsukja őket.

Szimbólumok eltávolítása

A szimbólumok általában a levágott szerelvényeknek megfelelően vannak levágva. Az összes szimbólumot is eltávolíthatja:

  • <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

    Távolítsa el a szimbólumokat a levágott alkalmazásból, beleértve a beágyazott PDF-fájlokat és a különálló PDB-fájlokat. Ez az alkalmazáskódra és a szimbólumokkal rendelkező függőségekre is vonatkozik.

Az SDK lehetővé teszi a hibakeresők támogatását is a tulajdonság DebuggerSupporthasználatával. Ha a hibakereső támogatása le van tiltva, a vágás automatikusan eltávolítja a szimbólumokat (TrimmerRemoveSymbols alapértelmezés szerint igaz).

A keretrendszertár funkcióinak kivágása

A keretrendszer-kódtárak több funkcióterülete tartalmaz olyan trimmer-irányelveket, amelyek lehetővé teszik a letiltott funkciók kódjának eltávolítását.

  • <AutoreleasePoolSupport>false</AutoreleasePoolSupport> (alapértelmezett)

    Távolítsa el az autorelease-készleteket támogató kódot a támogatott platformokon. A felügyelt szálakhoz lásd: AutoreleasePool. Ez a .NET SDK alapértelmezett beállítása.

  • <DebuggerSupport>false</DebuggerSupport>

    Távolítsa el a kódot, amely jobb hibakeresési szolgáltatásokat tesz lehetővé. Ez a beállítás a szimbólumokat is eltávolítja.

  • <EnableUnsafeBinaryFormatterSerialization>false</EnableUnsafeBinaryFormatterSerialization>

    Távolítsa el a BinaryFormatter szerializálási támogatását. További információ: BinaryFormatter szerializálási módszerek elavultak.

  • <EnableUnsafeUTF7Encoding>false</EnableUnsafeUTF7Encoding>

    Távolítsa el a nem biztonságos UTF-7 kódolási kódot. További információt az UTF-7 kódútvonalak elavultak.

  • <EventSourceSupport>false</EventSourceSupport>

    Távolítsa el az EventSource-tal kapcsolatos kódot vagy logikát.

  • <HttpActivityPropagationSupport>false</HttpActivityPropagationSupport>

    Távolítsa el a System.Net.Http diagnosztikai támogatásával kapcsolatos kódot.

  • <InvariantGlobalization>true</InvariantGlobalization>

    Távolítsa el a globalizációspecifikus kódot és adatokat. További információ: Invariant mód.

  • <MetadataUpdaterSupport>false</MetadataUpdaterSupport>

    Távolítsa el a gyakori újratöltéshez kapcsolódó metaadatok frissítésspecifikus logikáját.

  • <StackTraceSupport>false</StackTraceSupport> (.NET 8+)

    Távolítsa el a futtatókörnyezet által létrehozott verem-nyomkövetések (például Environment.StackTracevagy Exception.ToString) támogatását. A verem nyomkövetési sztringjeiből eltávolítandó információk mennyisége más üzembe helyezési lehetőségektől függhet. Ez a beállítás nem befolyásolja a hibakeresők által létrehozott verem-nyomkövetéseket.

  • <UseNativeHttpHandler>true</UseNativeHttpHandler>

    Használja az Android/iOS HttpMessageHandler alapértelmezett platformmegvalósítását, és távolítsa el a felügyelt implementációt.

  • <UseSystemResourceKeys>true</UseSystemResourceKeys>

    A szerelvények kivételüzeneteinek System.* csíkozása. Ha egy szerelvény kivételt System.* küld, az üzenet a teljes üzenet helyett egy egyszerűsített erőforrás-azonosító.

Ezek a tulajdonságok miatt a kapcsolódó kód le lesz vágva, és a runtimeconfig fájlon keresztül is letiltja a funkciókat. További információ ezekről a tulajdonságokról, beleértve a megfelelő futtatókörnyezet-konfigurációs beállításokat, tekintse meg a funkciókapcsolókat. Előfordulhat, hogy egyes SDK-k alapértelmezett értékekkel rendelkeznek ezekhez a tulajdonságokhoz.

A keretrendszer funkciói le vannak tiltva a vágáskor

Az alábbi funkciók nem kompatibilisek a vágással, mert statikusan nem hivatkozott kódot igényelnek. Ezek a funkciók alapértelmezés szerint le vannak tiltva a levágott alkalmazásokban.

Figyelmeztetés

Ezeket a funkciókat saját felelősségére engedélyezheti. A levágott alkalmazásokat valószínűleg további munka nélkül törik meg a dinamikusan hivatkozott kód megőrzése érdekében.

  • <BuiltInComInteropSupport>

    A beépített COM-támogatás le van tiltva.

  • <CustomResourceTypesSupport>

    Az egyéni erőforrástípusok használata nem támogatott. Az egyéni erőforrástípusokhoz tükröződő ResourceManager-kód elérési útjai levágva lesznek.

  • <EnableCppCLIHostActivation>

    A C++/CLI gazdagép aktiválása le van tiltva.

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    DesigntimeLicenseContextSerializerBinaryFormatter a szerializálás használata le van tiltva.

  • <StartupHookSupport>

    A kód korábbi MainDOTNET_STARTUP_HOOKS futtatása nem támogatott. További információkért tekintse meg a gazdagép indítási horogát.