Paketverweise (PackageReference) in ProjektdateienPackage references (PackageReference) in project files

Paketverweise über den PackageReference-Knoten verwalten NuGet-Abhängigkeiten direkt in den Projektdateien. Es wird keine separate packages.config-Datei benötigt.Package references, using the PackageReference node, manage NuGet dependencies directly within project files (as opposed to a separate packages.config file). Die Verwendung von PackageReference hat keine Auswirkungen auf andere Aspekte von NuGet. Einstellungen in Dateien vom Typ NuGet.config (Paketquellen eingeschlossen) gelten beispielsweise weiterhin wie unter Gängige NuGet-Konfigurationen beschrieben.Using PackageReference, as it's called, doesn't affect other aspects of NuGet; for example, settings in NuGet.config files (including package sources) are still applied as explained in Common NuGet configurations.

Mit PackageReference können Sie auch MSBuild-Bedingungen für die Auswahl von Paketverweisen pro Zielframework oder anderen Gruppierungen verwenden.With PackageReference, you can also use MSBuild conditions to choose package references per target framework, or other groupings. Zudem lässt er eine präzise Steuerung der Abhängigkeiten und des Inhaltsflusses zu.It also allows for fine-grained control over dependencies and content flow. (Informationen dazu finden Sie unter NuGet pack and restore as MSBuild targets – restore target (Packen und Wiederherstellen von NuGet als MSBuild-Ziele: Paketwiederherstellung).)(See For more details NuGet pack and restore as MSBuild targets.)

Unterstützung für ProjekttypenProject type support

Außer für C++ UWP-Projekte wird PackageReference standardmäßig nur in .NET Core-, .NET Standard- und UWP-Projekten für Windows 10 Build 15063 (Creators Update) und höher unterstützt.By default, PackageReference is used for .NET Core projects, .NET Standard projects, and UWP projects targeting Windows 10 Build 15063 (Creators Update) and later, with the exception of C++ UWP projects. .NET Framework-Projekte unterstützen PackageReference. Standardmäßig wird jedoch packages.config verwendet..NET Framework projects support PackageReference, but currently default to packages.config. Um PackageReference zu verwenden, migrieren Sie die Abhängigkeiten von packages.config zu Ihrer Projektdatei. Entfernen Sie anschließend „packages.config“.To use PackageReference, migrate the dependencies from packages.config into your project file, then remove packages.config.

ASP.NET-Apps für das vollständige .NET Framework enthalten nur eingeschränkte Unterstützung für PackageReference.ASP.NET apps targeting the full .NET Framework include only limited support for PackageReference. C++- und JavaScript-Projekttypen werden nicht unterstützt.C++ and JavaScript project types are unsupported.

Hinzufügen einer PackageReferenceAdding a PackageReference

Fügen Sie mit der folgenden Syntax eine Abhängigkeit in Ihrer Projektdatei hinzu:Add a dependency in your project file using the following syntax:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Steuern die AbhängigkeitsversionControlling dependency version

Die Konvention für die Angabe der Version eines Pakets entspricht der Verwendung von packages.config:The convention for specifying the version of a package is the same as when using packages.config:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Im obigen Beispiel steht 3.6.0 für eine beliebige Version >= 3.6.0, wobei die niedrigste Version bevorzugt wird, wie unter Paketversionsverwaltung beschrieben.In the example above, 3.6.0 means any version that is >=3.6.0 with preference for the lowest version, as described on Package versioning.

Verwenden von PackageReference für ein Projekt ohne PackageReferencesUsing PackageReference for a project with no PackageReferences

Erweitert: Wenn Sie keine Pakete in einem Projekt installiert haben (keine PackageReferences in der Projektdatei oder der packages.config-Datei), aber das Projekt mit dem Format von PackageReference wiederherstellen möchten, können Sie in der Projektdatei eine RestoreProjectStyle-Projekteigenschaft auf PackageReference festlegen.Advanced: If you have no packages installed in a project (no PackageReferences in project file and no packages.config file), but want the project to be restored as PackageReference style, you can set a Project property RestoreProjectStyle to PackageReference in your project file.

<PropertyGroup>
    <!--- ... -->
    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
    <!--- ... -->
</PropertyGroup>    

Dies kann sich als nützlich erweisen, wenn Sie auf Projekte verweisen, die das Format von PackageReference aufweisen (vorhandene Projekte im CSPROJ- oder SDK-Format).This may be useful, if you reference projects which are PackageReference styled (existing csproj or SDK-style projects). Dadurch kann Ihr Projekt „transitiv“ auf die Pakete verweisen, auf die diese Projekte verweisen.This will enable packages that those projects refer to, to be "transitively" referenced by your project.

PackageReference und QuellenPackageReference and sources

In PackageReference-Projekten werden transitive Abhängigkeitsversionen zur Wiederherstellungszeit aufgelöst.In PackageReference projects, the transitive dependency versions are resolved at restore time. Daher müssen in PackageReference-Projekten alle Quellen für alle Wiederherstellungen verfügbar sein.As such, in PackageReference projects all sources need to be available for all restores.

Unverankerte VersionenFloating Versions

Unverankerte Versionen werden mit PackageReference unterstützt:Floating versions are supported with PackageReference:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.*" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0-beta*" />
    <!-- ... -->
</ItemGroup>

Steuern von AbhängigkeitsobjektenControlling dependency assets

Sie verwenden eine Abhängigkeit möglicherweise rein als Entwicklungsumgebung und möchten diese nicht für Projekte verfügbar machen, die Ihr Paket nutzen.You might be using a dependency purely as a development harness and might not want to expose that to projects that will consume your package. In diesem Szenario können Sie dieses Verhalten über die PrivateAssets-Metadaten steuern.In this scenario, you can use the PrivateAssets metadata to control this behavior.

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <PrivateAssets>all</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

Mit den folgenden Metadatentags werden Abhängigkeitsobjekte gesteuert:The following metadata tags control dependency assets:

TagTag BeschreibungDescription StandardwertDefault Value
IncludeAssetsIncludeAssets Diese Objekte werden verbrauchtThese assets will be consumed alleall
ExcludeAssetsExcludeAssets Diese Objekte werden nicht verbrauchtThese assets will not be consumed Keinenone
PrivateAssetsPrivateAssets Diese Objekte werden verbraucht, aber nicht in das übergeordnete Projekt übertragenThese assets will be consumed but won't flow to the parent project contentfiles;analyzers;buildcontentfiles;analyzers;build

Folgende Werte sind für diese Tags zulässig, wobei mehrere Werte durch ein Semikolon (;) getrennt sind; eine Ausnahme stellen all und none dar, die nur alleine dargestellt werden dürfen:Allowable values for these tags are as follows, with multiple values separated by a semicolon except with all and none which must appear by themselves:

WertValue BeschreibungDescription
compilecompile Inhalt des Ordners lib und steuert, ob Ihr Projekt anhand der Assemblys im Ordner kompiliert werden kannContents of the lib folder and controls whether your project can compile against the assemblies within the folder
Laufzeitruntime Inhalt der Ordner lib und runtimes und steuert, ob diese Assemblys in das Buildausgabeverzeichnis kopiert werdenContents of the lib and runtimes folder and controls whether these assemblies will be copied out to the build output directory
contentFilescontentFiles Inhalte des Ordners contentfilesContents of the contentfiles folder
buildbuild .props und .targets im Ordner build.props and .targets in the build folder
buildMultitargetingbuildMultitargeting (4.0) .props und .targets im Ordner buildMultitargeting für frameworkübergreifende Zielplattformen(4.0) .props and .targets in the buildMultitargeting folder, for cross-framework targeting
buildTransitivebuildTransitive (5.0 und höher) .props und .targets im Ordner buildTransitive für Ressourcen, die transitiv in beliebige verarbeitende Projekte eingefügt werden.(5.0+) .props and .targets in the buildTransitive folder, for assets that flow transitively to any consuming project. Weitere Informationen finden Sie auf der Seite Feature.See the feature page.
Analysetoolsanalyzers .NET-Analystetools.NET analyzers
Systemeigennative Inhalte des Ordners nativeContents of the native folder
Keinenone Keiner der obigen Werte wird verwendet.None of the above are used.
alleall Alle oben genannten Werte (mit Ausnahme von none)All of the above (except none)

Im folgenden Beispiel wird im Projekt bis auf die Inhaltsdateien aus dem Paket alles verwendet, und alles bis auf die Inhaltsdateien und Analysetools wird in das übergeordnete Projekt übertragen.In the following example, everything except the content files from the package would be consumed by the project and everything except content files and analyzers would flow to the parent project.

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets>
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

Beachten Sie Folgendes: Da build nicht in PrivateAssets enthalten ist, werden Ziele und Eigenschaften an das übergeordnete Projekt übergeben.Note that because build is not included with PrivateAssets, targets and props will flow to the parent project. Angenommen, der obenstehende Verweis wird in einem Projekt verwendet, in dem ein NuGet-Paket mit dem Namen AppLogger erstellt wird.Consider, for example, that the reference above is used in a project that builds a NuGet package called AppLogger. AppLogger kann die Ziele und Eigenschaften aus Contoso.Utility.UsefulStuff verarbeiten, wie Projekte, die AppLogger verarbeiten.AppLogger can consume the targets and props from Contoso.Utility.UsefulStuff, as can projects that consume AppLogger.

Hinweis

Wenn developmentDependency in einer .nuspec-Datei auf true festgelegt ist, kennzeichnet dies ein Paket mit einer Abhängigkeit, die nur für die Entwicklung gilt. Dadurch wird vermieden, dass das Paket als Abhängigkeit in andere Pakete eingefügt wird.When developmentDependency is set to true in a .nuspec file, this marks a package as a development-only dependency, which prevents the package from being included as a dependency in other packages. Bei PackageReference (NuGet 4.8+) bedeutet dieses Flag auch, dass Objekte zur Kompilierzeit von der Kompilierung ausgeschlossen werden.With PackageReference (NuGet 4.8+), this flag also means that it will exclude compile-time assets from compilation. Weitere Informationen finden Sie unter DevelopmentDependency support for PackageReference (DevelopmentDependency-Unterstützung für PackageReference).For more information, see DevelopmentDependency support for PackageReference.

Hinzufügen einer PackageReference-BedingungAdding a PackageReference condition

Sie können mithilfe einer Bedingung steuern, ob ein Paket eingeschlossen wird. Dabei kann in Bedingungen eine beliebige MSBuild-Variable oder eine in der Ziel- oder Eigenschaftendatei definierte Variable verwendet werden.You can use a condition to control whether a package is included, where conditions can use any MSBuild variable or a variable defined in the targets or props file. Zum aktuellen Zeitpunkt wird jedoch nur die Variable TargetFramework unterstützt.However, at presently, only the TargetFramework variable is supported.

Angenommen, Ihre Zielgruppen lauten netstandard1.4 und net452, die vorhandene Abhängigkeit gilt jedoch nur für net452.For example, say you're targeting netstandard1.4 as well as net452 but have a dependency that is applicable only for net452. In diesem Fall sollte diese unnötige Abhängigkeit nicht zu einem netstandard1.4-Projekt hinzugefügt werden, in dem Ihr Paket verwendet wird.In this case you don't want a netstandard1.4 project that's consuming your package to add that unnecessary dependency. Sie geben in der PackageReference eine Bedingung an, um dies zu verhindern, die wie folgt lautet:To prevent this, you specify a condition on the PackageReference as follows:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
    <!-- ... -->
</ItemGroup>

Ein Paket, das in diesem Projekt erstellt wurde, zeigt an, dass die Datei „Newtonsoft.json“ nur als Abhängigkeit für ein net452-Ziel enthalten ist:A package built using this project will show that Newtonsoft.Json is included as a dependency only for a net452 target:

Das Ergebnis der Anwendung einer Bedingung auf die PackageReference mit VS2017

Bedingungen können auch auf der ItemGroup-Ebene angewendet werden und gelten dann für alle untergeordneten PackageReference-Elemente:Conditions can also be applied at the ItemGroup level and will apply to all children PackageReference elements:

<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

GeneratePathPropertyGeneratePathProperty

Dieses Feature ist mit NuGet 5.0 oder höher und mit Visual Studio 2019 16.0 oder höher verfügbar.This feature is available with NuGet 5.0 or above and with Visual Studio 2019 16.0 or above.

Manchmal ist es wünschenswert, von einem MSBuild-Ziel aus auf Dateien in einem Paket zu verweisen.Sometimes it is desirable to reference files in a package from an MSBuild target. In packages.config-basierten Projekten werden die Pakete in einem Ordner mit Bezug zur Projektdatei installiert.In packages.config based projects, the packages are installed in a folder relative to the project file. Bei PackageReference werden die Pakete hingegen aus dem Ordner global-packages verwendet, der von Computer zu Computer variieren kann.However in PackageReference, the packages are consumed from the global-packages folder, which can vary from machine to machine.

Um diese Lücke zu schließen, wurde in NuGet eine Eigenschaft eingeführt, die auf den Speicherort verweist, von dem aus das Paket verwendet wird.To bridge that gap, NuGet introduced a property that points to the location from which the package will be consumed.

Beispiel:Example:

  <ItemGroup>
      <PackageReference Include="Some.Package" Version="1.0.0" GeneratePathProperty="true" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgSome_Package)\something.exe" />
  </Target>

Zusätzlich werden von NuGet automatisch Eigenschaften für Pakete generiert, die einen Tools-Ordner enthalten.Additionally NuGet will automatically generate properties for packages containing a tools folder.

  <ItemGroup>
      <PackageReference Include="Package.With.Tools" Version="1.0.0" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgPackage_With_Tools)\tools\tool.exe" />
  </Target>

MSBuild-Eigenschaften und Paketidentitäten haben nicht die gleichen Einschränkungen, sodass die Paketidentität in einen MSBuild-Anzeigenamen geändert werden muss, dem das Wort Pkg vorangestellt ist.MSBuild properties and package identities do not have the same restrictions so the package identity needs to be changed to an MSBuild friendly name, prefixed by the word Pkg. Beachten Sie die generierte nuget.g.props-Datei, um den genauen Namen der generierten Eigenschaft zu überprüfen.To verify the exact name of the property generated, look at the generated nuget.g.props file.

NuGet-Warnungen und -FehlerNuGet warnings and errors

Dieses Feature ist mit NuGet 4.3 oder höher und mit Visual Studio 2017 15.3 oder höher verfügbar.This feature is available with NuGet 4.3 or above and with Visual Studio 2017 15.3 or above.

Für viele Pack- und Wiederherstellungsszenarios werden alle NuGet-Warnungen und -Fehler codiert, und sie beginnen mit NU****.For many pack and restore scenarios, all NuGet warnings and errors are coded, and start with NU****. Alle NuGet-Warnungen und -Fehler sind in der Referenz-Dokumentation aufgeführt.All NuGet warnings and errors are listed in the reference documentation.

NuGet beachtet die folgenden Warnungseigenschaften:NuGet observes the following warning properties:

  • TreatWarningsAsErrors, alle Warnungen als Fehler behandelnTreatWarningsAsErrors, treat all warnings as errors
  • WarningsAsErrors, bestimmte Warnungen als Fehler behandelnWarningsAsErrors, treat specific warnings as errors
  • NoWarn, bestimmte Warnungen ausblenden, entweder projekt- oder paketweit.NoWarn, hide specific warnings, either project-wide or package-wide.

Beispiele:Examples:

<PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <WarningsAsErrors>$(WarningsAsErrors);NU1603;NU1605</WarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <NoWarn>$(NoWarn);NU5124</NoWarn>
</PropertyGroup>
...
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0" NoWarn="NU1605" />
</ItemGroup>

Unterdrücken von NuGet-WarnungenSuppressing NuGet warnings

Es wird empfohlen, alle NuGet-Warnungen während der Pack- und Wiederherstellungsvorgänge aufzulösen; in bestimmten Situationen wird deren Auflösung verlangt.While it is recommended that you resolve all NuGet warnings during your pack and restore operations, in certain situations suppressing them is warranted. Für die projektweite Unterdrückung einer Warnung sollten Sie Folgendes in Erwägung ziehen:To suppress a warning project wide, consider doing:

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
    <NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1"/>
</ItemGroup>

Gelegentlich beziehen sich Warnungen nur auf ein bestimmtes Paket im Graph.Sometimes warnings apply only to a certain package in the graph. Sie können eine solche Warnung selektiv unterdrücken, indem Sie im PackageReference-Element NoWarn hinzufügen.We can choose to suppress that warning more selectively by adding a NoWarn on the PackageReference item.

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1" NoWarn="NU1603" />
</ItemGroup>

Unterdrücken von Warnungen für NuGet-Pakete in Visual StudioSuppressing NuGet package warnings in Visual Studio

In Visual Studio ist das Unterdrücken von Warnungen auch über die IDE möglich.When in Visual Studio, you can also suppress warnings through the IDE.

Sperren von AbhängigkeitenLocking dependencies

Dieses Feature ist mit NuGet 4.9 oder höher und mit Visual Studio 2017 15.9 oder höher verfügbar.This feature is available with NuGet 4.9 or above and with Visual Studio 2017 15.9 or above.

Die Eingabe für die NuGet-Wiederherstellung ist ein Satz mit Paketverweisen aus der Projektdatei (oberste Ebene oder direkte Abhängigkeiten). Die Ausgabe ist der vollständige Abschluss aller Paketabhängigkeiten einschließlich transitiver Abhängigkeiten.Input to NuGet restore is a set of Package References from the project file (top-level or direct dependencies) and the output is a full closure of all the package dependencies including transitive dependencies. NuGet versucht immer, den gleichen vollständigen Abschluss von Paketabhängigkeiten zu erzeugen, wenn sich die PackageReference-Eingabeliste nicht geändert hat.NuGet tries to always produce the same full closure of package dependencies if the input PackageReference list has not changed. Es gibt jedoch einige Szenarien, in denen dies nicht möglich ist.However, there are some scenarios where it is unable to do so. Zum Beispiel:For example:

  • Beim Verwenden von unverankerten Versionen wie <PackageReference Include="My.Sample.Lib" Version="4.*"/>.When you use floating versions like <PackageReference Include="My.Sample.Lib" Version="4.*"/>. Während die Absicht hierbei darin liegt, bei jeder Wiederherstellung die neueste Version zu verwenden, gibt es Szenarien, in denen Benutzer anfordern, dass der Paketgraph auf eine bestimmte neueste Version festgelegt und zu einem späteren Zeitpunkt ggf. explizit eine höhere Version geändert werden kann.While the intention here is to float to the latest version on every restore of packages, there are scenarios where users require the graph to be locked to a certain latest version and float to a later version, if available, upon an explicit gesture.

  • Eine neuere Version des Pakets, die den Anforderungen an die PackageReference-Version entspricht, wird veröffentlicht.A newer version of the package matching PackageReference version requirements is published. Beispiel:E.g.

    • Tag 1: Sie haben <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> angegeben, aber die in den NuGet-Repositorys verfügbaren Versionen waren 4.1.0, 4.2.0 und 4.3.0.Day 1: if you specified <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> but the versions available on the NuGet repositories were 4.1.0, 4.2.0 and 4.3.0. In diesem Fall verwendet NuGet die Version 4.1.0 (die nächste verfügbare Mindestversion).In this case, NuGet would have resolved to 4.1.0 (nearest minimum version)

    • Tag 2: Version 4.0.0 wird veröffentlicht.Day 2: Version 4.0.0 gets published. NuGet findet jetzt die exakte Übereinstimmung und beginnt mit der Verwendung von 4.0.0.NuGet will now find the exact match and start resolving to 4.0.0

  • Eine bestimmte Paketversion wird aus dem Repository entfernt.A given package version is removed from the repository. Auch wenn nuget.org das Löschen von Paketen nicht erlaubt, weisen nicht alle Paketrepositorys diese Einschränkung auf.Though nuget.org does not allow package deletions, not all package repositories have this constraints. Daher sucht NuGet nach der besten Übereinstimmung, wenn die gelöschte Version nicht verwendet werden kann.This results in NuGet finding the best match when it cannot resolve to the deleted version.

Aktivieren einer SperrdateiEnabling lock file

Um den vollständigen Abschluss von Paketabhängigkeiten beizubehalten, können Sie die Funktion einer Sperrdatei einrichten, indem Sie die MSBuild-Eigenschaft RestorePackagesWithLockFile für Ihr Projekt festlegen:In order to persist the full closure of package dependencies you can opt-in to the lock file feature by setting the MSBuild property RestorePackagesWithLockFile for your project:

<PropertyGroup>
    <!--- ... -->
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    <!--- ... -->
</PropertyGroup>    

Wenn diese Eigenschaft festgelegt ist, generiert NuGet eine Sperrdatei – packages.lock.json-Datei – im Projektstammverzeichnis, die alle Paketabhängigkeiten auflistet.If this property is set, NuGet restore will generate a lock file - packages.lock.json file at the project root directory that lists all the package dependencies.

Hinweis

Sobald ein Projekt eine packages.lock.json-Datei im Stammverzeichnis enthält, wird die Sperrdatei bei der Wiederherstellung immer verwendet, auch wenn die Eigenschaft RestorePackagesWithLockFile nicht festgelegt ist.Once a project has packages.lock.json file in its root directory, the lock file is always used with restore even if the property RestorePackagesWithLockFile is not set. Eine andere Möglichkeit zur Verwendung dieser Funktion besteht also darin, eine leere packages.lock.json-Dummydatei im Stammverzeichnis des Projekts zu erstellen.So another way to opt-in to this feature is to create a dummy blank packages.lock.json file in the project's root directory.

restore-Verhalten mit Sperrdateirestore behavior with lock file

Wenn für ein Projekt eine Sperrdatei vorhanden ist, verwendet NuGet diese Sperrdatei zum Ausführen von restore.If a lock file is present for project, NuGet uses this lock file to run restore. NuGet überprüft, ob Änderungen an den Paketabhängigkeiten vorgenommen wurden, die in der Projektdatei (bzw. in Projektdateien von abhängigen Projekten) definiert wurden. Wenn keine Änderungen vorhanden sind, stellt NuGet einfach die in der Sperrdatei angegebenen Pakete wieder her.NuGet does a quick check to see if there were any changes in the package dependencies as mentioned in the project file (or dependent projects' files) and if there were no changes it just restores the packages mentioned in the lock file. Es erfolgt keine erneute Auswertung der Paketabhängigkeiten.There is no re-evaluation of package dependencies.

Wenn NuGet eine Änderung bei den in den Projektdateien definierten Abhängigkeiten ermittelt, wird der Paketgraph erneut ausgewertet, und die Sperrdatei wird aktualisiert, um den neuen Paketabschluss für das Projekt widerzuspiegeln.If NuGet detects a change in the defined dependencies as mentioned in the project file(s), it re-evaluates the package graph and updates the lock file to reflect the new package closure for the project.

Für CI/CD- und andere Szenarien, in denen Paketabhängigkeiten nicht dynamisch geändert werden dürfen, können Sie dies erreichen, indem Sie lockedmode auf true festlegen:For CI/CD and other scenarios, where you would not want to change the package dependencies on the fly, you can do so by setting the lockedmode to true:

Führen Sie für dotnet.exe folgenden Befehl aus:For dotnet.exe, run:

> dotnet.exe restore --locked-mode

Führen Sie für msbuild.exe folgenden Befehl aus:For msbuild.exe, run:

> msbuild.exe -t:restore -p:RestoreLockedMode=true

Sie können diese bedingte MSBuild-Eigenschaft auch in Ihrer Projektdatei festlegen:You may also set this conditional MSBuild property in your project file:

<PropertyGroup>
    <!--- ... -->
    <RestoreLockedMode>true</RestoreLockedMode>
    <!--- ... -->
</PropertyGroup> 

Wenn der Sperrmodus true lautet, gilt Folgendes: Bei der Wiederherstellung werden entweder die Pakete genau so wiederhergestellt wie in der Sperrdatei aufgelistet, oder es tritt ein Fehler auf, wenn Sie die definierten Paketabhängigkeiten für das Projekt nach dem Erstellen der Sperrdatei aktualisiert haben.If locked mode is true, restore will either restore the exact packages as listed in the lock file or fail if you updated the defined package dependencies for the project after lock file was created.

Einbinden der Sperrdatei als Teil Ihres QuellrepositorysMake lock file part of your source repository

Wenn Sie eine Anwendung oder eine ausführbare Datei erstellen und sich das fragliche Projekt am Anfang der Abhängigkeitskette befindet, checken Sie die Sperrdatei im Quellcoderepository ein, damit NuGet diese während der Wiederherstellung verwenden kann.If you are building an application, an executable and the project in question is at the start of the dependency chain then do check in the lock file to the source code repository so that NuGet can make use of it during restore.

Wenn es sich bei Ihrem Projekt aber um ein nicht auszulieferndes Bibliotheksprojekt oder ein Projekt mit gemeinsamem Code handelt, von dem andere Projekte abhängig sind, sollten Sie die Sperrdatei nicht als Teil Ihres Quellcodes einchecken.However, if your project is a library project that you do not ship or a common code project on which other projects depend upon, you should not check in the lock file as part of your source code. Es schadet nicht, die Sperrdatei zu behalten, aber die gesperrten Paketabhängigkeiten für das Projekt mit gemeinsamem Code werden möglicherweise während der Wiederherstellung bzw. Erstellung eines Projekts, das von diesem Projekt mit gemeinsamem Code abhängig ist, nicht wie in der Sperrdatei aufgelistet verwendet.There is no harm in keeping the lock file but the locked package dependencies for the common code project may not be used, as listed in the lock file, during the restore/build of a project that depends on this common-code project.

Beispiel:Eg.

ProjectA
  |------> PackageX 2.0.0
  |------> ProjectB
             |------>PackageX 1.0.0

Wenn ProjectA eine Abhängigkeit von einer PackageX-Version 2.0.0 aufweist und auch auf ProjectB verweist, das von der PackageX-Version 1.0.0 abhängig ist, listet die Sperrdatei für ProjectB eine Abhängigkeit von der PackageX-Version 1.0.0 auf.If ProjectA has a dependency on a PackageX version 2.0.0 and also references ProjectB that depends on PackageX version 1.0.0, then the lock file for ProjectB will list a dependency on PackageX version 1.0.0. Wenn ProjectA jedoch erstellt wird, enthält die Sperrdatei eine Abhängigkeit von der PackageX-Version 2.0.0 und nicht von 1.0.0, wie in der Sperrdatei für ProjectB aufgelistet.However, when ProjectA is built, its lock file will contain a dependency on PackageX version 2.0.0 and not 1.0.0 as listed in the lock file for ProjectB. Daher hat die Sperrdatei eines Projekts mit gemeinsamem Code nur wenig Aussagekraft für die verwendeten Pakete für Projekte, die von diesem Projekt abhängig sind.Thus, the lock file of a common code project has little say over the packages resolved for projects that depend on it.

Erweiterbarkeit der SperrdateiLock file extensibility

Sie können mit einer Sperrdatei verschiedene Verhaltensweisen der Wiederherstellung steuern, wie im Folgenden beschrieben:You can control various behaviors of restore with lock file as described below:

NuGet.exe-OptionNuGet.exe option dotnet-Optiondotnet option Entsprechende MSBuild-OptionMSBuild equivalent option BeschreibungDescription
-UseLockFile --use-lock-file RestorePackagesWithLockFileRestorePackagesWithLockFile Ermöglicht die Verwendung einer Sperrdatei.Opts into the usage of a lock file.
-LockedMode --locked-mode RestoreLockedModeRestoreLockedMode Ermöglicht den Sperrmodus für die Wiederherstellung.Enables locked mode for restore. Dies ist nützlich in CI/CD-Szenarien, in denen Sie wiederholbare Builds wünschen.This is useful in CI/CD scenarios where you want repeatable builds.
-ForceEvaluate --force-evaluate RestoreForceEvaluateRestoreForceEvaluate Diese Option ist nützlich bei Paketen, bei denen im Projekt unverankerte Versionen definiert sind.This option is useful with packages with floating version defined in the project. Standardmäßig aktualisiert die NuGet-Wiederherstellung die Paketversion nicht automatisch bei jedem Wiederherstellungsvorgang, wenn Sie diesen Vorgang nicht mit dieser Option ausführen.By default, NuGet restore will not update the package version automatically upon each restore unless you run restore with this option.
-LockFilePath --lock-file-path NuGetLockFilePathNuGetLockFilePath Definiert einen benutzerdefinierten Speicherort der Sperrdatei für ein Projekt.Defines a custom lock file location for a project. Standardmäßig unterstützt NuGet packages.lock.json im Stammverzeichnis.By default, NuGet supports packages.lock.json at the root directory. Wenn Sie über mehrere Projekte im gleichen Verzeichnis verfügen, unterstützt NuGet die projektspezifische Sperrdatei packages.<project_name>.lock.json.If you have multiple projects in the same directory, NuGet supports project specific lock file packages.<project_name>.lock.json