What is Package Source Mapping?

Package Source Mapping allows you to select which nuget source can download specific packages. Think of it as a security guard that checks if packages come from authorized sources before letting them into your project. Here’s why you should use it in your .NET projects:

1. Faster Builds: Your builds run quicker because NuGet skips searching for private packages in public repositories
2. Enhanced Security: Stop package hijacking attacks by ensuring packages come only from trusted sources
3. Better Organization: Keep internal and public packages clearly separated for easier project management
4. Regulatory Compliance: Ensure company packages download only from internal repositories to meet compliance requirements

How it works?

Package source mapping provides fine-grained control over which source is used to download dependencies. You can connect specific packages to one or more sources, letting you download different packages from different locations. Common case to use it is:

• Download company packages from company private feed
• Get open-source packages from the public NuGet feed

The mapping system uses patterns to match packages, with specific patterns taking priority over general ones. Here’s an example:

• FinalException.Common (specific pattern)
• FinalException.* (general pattern)

When you use the FinalException.Common.CQRS package, the system checks the specific pattern first and uses its designated source. In given example, it will match with specific pattern and use source connected to it.

Setting Up Package Source Mapping

First, you need create or update your nuget.config file in your solution’s root directory. Here’s a clear example:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="finalexception" value="https://finalexception.com/packages/" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="finalexception">
      <package pattern="FinalException.*" />
      <package pattern="NuGet.Common" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Let’s break down this configuration:

1. Define Package Sources:

• The <clear /> tag prevents inheriting unwanted sources from other config files
• Each source needs a unique key identifier and a value URL
• This example sets up both the public NuGet feed and a custom FinalException feed

1. Create Package Mappings:

• Map patterns to specific sources using the <packageSourceMapping> section
• The * pattern under nuget.org catches all packages by default
• Specific patterns like FinalException.* route matching packages to the custom source

Conclusion

Package Source Mapping helps you build faster and more secure .NET applications. Start with broad patterns and make them more specific as needed. This guide shows you how to enhance your project’s security while speeding up builds.

Want to learn more? Check out Microsoft’s official documentation on: https://learn.microsoft.com/en-us/nuget/consume-packages/package-source-mapping