DOCSEARCHbyAlgolia
Submit Docs

NuGet Documentation

repository·main·Indexed 41 days ago

https://github.com/nuget/docs.microsoft.com-nuget

Official documentation for NuGet, the core package management technology. Includes guides on using nuget.exe, NuGet.Config, and the NuGet V3 API, including detailed specifications for the Catalog resource, Catalog Index, and Catalog Leaves.

Tokens
262.1K
Snippets
651
Records
1.1K
Agent score
50%

What's inside NuGet

  1. Overview of the NuGet Ecosystem

    main

    The NuGet ecosystem is a broad collection of tools, services, and projects built around the NuGet package management system. Because NuGet is open source under the Apache v2 license, it serves as a foundation for various enterprise and open-source tools.

    Key components include:

    • The NuGet Project: Comprised of client tools and the official NuGet Gallery (nuget.org), governed by the .NET Foundation.
    • Microsoft Contributions: Extensive open-source contributions donated to the .NET Foundation.
    • Third-party Ecosystem: A wide range of non-Microsoft projects including CI/CD tools (AppVeyor, TeamCity), package servers (Artifactory, ProGet, Sonatype Nexus), and specialized utilities (NuGet Package Explorer, Paket).

  2. Overview of the NuGet Client SDK packages

    main

    The NuGet Client SDK is a collection of libraries used to build NuGet clients and tools. Key packages include:

    • NuGet.Protocol: APIs for interacting with HTTP and file-based NuGet feeds.
    • NuGet.Packaging: APIs for interacting with .nupkg and .nuspec files via streams.
    • NuGet.Common: Common utilities and interfaces.
    • NuGet.Configuration: Configuration settings implementation.
    • NuGet.Credentials: Authentication models.
    • NuGet.Versioning: Semantic Versioning implementation.
    • NuGet.DependencyResolver.Core: PackageReference dependency resolver.
    • NuGet.ProjectModel: Core types for PackageReference-based restore (lock files, assets files).
    • NuGet.Frameworks: Target framework understanding.
    • NuGet.LibraryModel: Types and interfaces for understanding dependencies.
    • NuGet.Indexing: Indexing library for Visual Studio search.
    • NuGet.Commands: Common commands for CLI and GUI clients.
    • NuGet.Localization: Localization support.
    • NuGet.PackageManagement: Package management for Visual Studio installation flow.
    • NuGet.Resolver: Dependency resolver for packages.config projects.

  3. Understand the NuGet Server API (V3)

    main

    The NuGet Server API is a set of HTTP endpoints used to download packages, fetch metadata, and publish new packages. It is the same protocol used by official clients like Visual Studio, nuget.exe, and the .NET CLI (e.g., for dotnet restore).

    Key Concepts

    • Protocol Version: This documentation refers to the V3 API. The service index schema version must have a major version of 3.
    • Service Index: The entry point for any client. It is a JSON document located at a well-known URL (e.g., https://api.nuget.org/v3/index.json) that contains a list of available resources.
    • Resources: Different endpoints that provide specific functionality (e.g., searching, downloading, or publishing).

  4. Options for hosting your own NuGet feeds

    main

    If you need to release packages to a limited audience (like an organization) or restrict developers to specific third-party libraries, you can host your own NuGet feeds. There are three primary ways to host locally or via a self-managed server:

    • Local feed: Packages are stored on a local or network file share. For NuGet 3.3+, it is recommended to use nuget init and nuget add to create a hierarchical folder structure.
    • NuGet.Server: Packages are served via a local HTTP server.
    • NuGet Gallery: A full-featured web UI (similar to nuget.org) for searching and exploring packages, built using the NuGet Gallery Project.

    Additionally, many managed and third-party services support NuGet feeds, including Azure Artifacts, GitHub Package Registry, Artifactory, and others.

  5. Repository structure and key files

    main

    The NuGet documentation repository is organized as follows:

    • docs/: Contains all markdown files and subfolders.
    • docs/index.md: Defines the landing (hub) page.
    • docs/TOC.md: Defines the left-hand navigation panel.
    • docs/docfx.json: Contains metadata defaults.
    • docs/.openpublishing.redirection.json: Maps old filenames to new ones for redirects.
    • docs/_breadcrumb/toc.yml: Defines the breadcrumbs displayed on the site.
    • media/: Subfolders within topic directories containing images.

  6. What is Package Source Mapping?

    main

    Package Source Mapping is a security feature used to improve supply chain security when using a mix of public and private package sources.

    By default, NuGet searches all configured sources for a package, which can lead to non-deterministic behavior if a package exists on multiple sources. Package Source Mapping allows you to filter, on a per-package basis, exactly which source(s) NuGet is permitted to search for specific package patterns. This prevents 'dependency confusion' attacks where a malicious package with the same name is uploaded to a public repository.

  7. What is PackageDownload and when to use it

    main

    Overview

    PackageDownload is a utility feature for .NET SDK-style projects, introduced in NuGet 5.3. It acts as a companion to PackageReference but with a different purpose.

    While PackageReference manages dependencies that are automatically added to your project for compile and runtime use, PackageDownload allows you to download packages to your global packages folder without including their assets (like assemblies) in your project.

    When to use PackageDownload

    Use PackageDownload when you need to download packages that:

    • Do not follow the traditional NuGet package structure.
    • Primarily carry build-time dependencies.
    • You want to download to a specific location (similar to a packages.config file not tied to a project) without the overhead of full dependency management.

    Key Differences from PackageReference

    FeaturePackageReferencePackageDownload
    Package assets selectionAssemblies are automatically added to the project for compile/runtimeNo assets from the package are included in the project
    DependenciesAutomatically resolved and flattenedNot considered at all
    TransitivityAutomatically propagated to dependent projectsIgnored by dependent projects
    Version supportSupports ranges (e.g., 1.0.0 or [1.0.0, ))Only exact versions supported
    dotnet list packageAll dependencies are includedNot shown by dotnet list package
    packIncluded in the package specificationNot included in the package specification

  8. What is Trusted Publishing on nuget.org

    main

    Trusted Publishing is a secure, keyless method for publishing NuGet packages using short-lived credentials issued by your CI/CD system (e.g., GitHub Actions or GitLab) via OpenID Connect (OIDC).

    Instead of managing long-lived API keys that risk being leaked, your workflow requests an encrypted OIDC token from your DevSecOps platform. This token is sent to nuget.org, which validates it against a pre-configured Trusted Publishing policy. If the token matches the policy, nuget.org issues a temporary API key valid for 1 hour.

    Key constraints:

    • Each short-lived token can only be used once to obtain a single temporary API key.
    • Request the key shortly before the push operation to avoid expiration.

  9. What is a NuGet package?

    main

    A NuGet package is a single ZIP file with the .nupkg extension. It serves as a shareable unit of code for .NET (including .NET Core) and contains:

    • Compiled code: Typically DLLs.
    • Related content: Other files required by the code.
    • Descriptive manifest: Metadata including the package's version number and other descriptive information.

    Developers use NuGet to create, host, and consume these packages to share code within an organization or across the public ecosystem.

  10. Dependency resolution with PackageReference

    main

    When using the PackageReference format, NuGet performs transitive restore. This process resolves the entire dependency graph ahead of time and writes the resulting graph to a file named project.assets.json located in the MSBuildProjectExtensionsPath (which defaults to the project's obj folder).

    Key characteristics of PackageReference resolution:

    • Predictability: Reinstalling or restoring packages simply involves downloading the packages listed in the pre-calculated graph, leading to faster and more predictable builds.
    • Floating Versions: You can use floating versions (e.g., 2.8.*) to automatically use the latest version within a range. To ensure build repeatability when using floating versions, it is recommended to enable lock file functionality.
    • Assets File: The project.assets.json file is a temporary file used by MSBuild to translate the graph into project references. Do not add this file to source control; it is excluded by default in .gitignore and .tfignore.

  11. Understand NuGet package asset types for native libraries

    main

    When creating .NET packages that include native libraries, NuGet uses three primary asset types to manage how files are selected and copied to the consumer's output directory based on their Runtime Identifier (RID) and Target Framework (TFM):

    • Compile assets: Managed assemblies used by the compiler. These should be placed in ref/{tfm}/ (preferred for native interop packages) or lib/{tfm}/.
    • Runtime assets: Managed assemblies copied to the output directory at runtime. These should be placed in runtimes/{rid}/lib/{tfm}/ to ensure compatibility with the .NET runtime's probing paths.
    • Native assets: Native libraries (e.g., .dll, .so, .dylib) copied to the output directory. These must be placed in runtimes/{rid}/native/.

    Important: Avoid using the contentFiles/ feature for native libraries, as it does not support per-RID selection and will not participate in the .NET runtime's probing paths.

    |Asset type|Short Description|
|--|--|
|[compile](#compile-assets)|Managed assemblies passed to the compiler. `ref/{tfm}/` if it exists, otherwise `lib/{tfm}/`.|
|[runtime](#runtime-assets)|Managed assemblies copied to the output directory. `runtimes/{rid}/lib/{tfm}/` if it exists, otherwise `lib/{tfm}/`.|
|[native](#native-assets)|Native libraries copied to the output directory. `runtimes/{rid}/native/`|

  12. How PackageReference selects compile and runtime assets

    main

    When a consumer uses PackageReference, NuGet selects assets based on specific directory structures:

    1. Compile Assets: NuGet prefers assemblies in ref/<tfm>/*.dll (e.g., ref/net6.0/*.dll). If these are missing, it falls back to lib/<tfm>/*.dll (e.g., lib/net6.0/*.dll). Using ref/ allows you to provide metadata-only assemblies to reduce package size.
    2. Runtime Assets: NuGet prefers assemblies in runtimes/<rid>/lib/<tfm>/*.dll (e.g., runtimes/win11-x64/lib/net6.0/*.dll). If these are missing, it falls back to lib/<tfm>/*.dll.