Documentation
¶
Overview ¶
Package assets implements NuGet's pattern-based asset selection engine. This system matches package files to target frameworks and runtime identifiers using property-based pattern definitions.
Reference: NuGet.Packaging/ContentModel/
Index ¶
- Variables
- func FilterToDllExe(paths []string) []string
- func GetLibItems(files []string, targetFramework *frameworks.NuGetFramework, ...) []string
- func GetLockFileItems(criteria *SelectionCriteria, collection *ContentItemCollection, ...) []string
- func GetRefItems(files []string, targetFramework *frameworks.NuGetFramework, ...) []string
- type CompareTest
- type CompatibilityProfile
- type CompatibilityTest
- type ContentItem
- type ContentItemCollection
- type ContentItemGroup
- type FrameworkRuntimePair
- type LiteralSegment
- type ManagedCodeConventions
- type PatternDefinition
- type PatternExpression
- type PatternSet
- type PatternTable
- type PatternTableEntry
- type PropertyDefinition
- type PropertyParser
- type RuntimeDependencySet
- type RuntimeDescription
- type RuntimeGraph
- func (g *RuntimeGraph) AddRuntime(rid string, imports []string)
- func (g *RuntimeGraph) AreCompatible(targetRID, packageRID string) bool
- func (g *RuntimeGraph) ExpandRuntime(rid string) []string
- func (g *RuntimeGraph) FindRuntimeDependencies(runtimeName, packageID string) []*RuntimePackageDependency
- func (g *RuntimeGraph) GetAllCompatibleRIDs(targetRID string) []string
- type RuntimeIdentifier
- type RuntimePackageDependency
- type Segment
- type SelectionCriteria
- type SelectionCriteriaBuilder
- type SelectionCriteriaEntry
- type TokenSegment
Constants ¶
This section is empty.
Variables ¶
var AnyTable = NewPatternTable([]PatternTableEntry{ { PropertyName: "tfm", Name: "any", Value: frameworks.AnyFramework, }, })
AnyTable maps "any" to AnyFramework.
var DotnetAnyTable = NewPatternTable([]PatternTableEntry{ { PropertyName: "tfm", Name: "any", Value: frameworks.CommonFrameworks.DotNet, }, })
DotnetAnyTable maps "any" to DotNet framework.
Functions ¶
func FilterToDllExe ¶
FilterToDllExe filters paths to DLL/EXE/WINMD files.
func GetLibItems ¶
func GetLibItems(files []string, targetFramework *frameworks.NuGetFramework, conventions *ManagedCodeConventions) []string
GetLibItems gets runtime assemblies for target framework. Uses RuntimeAssemblies pattern set and filters to DLL/EXE/WINMD files. Reference: LockFileUtils.cs CreateLockFileTargetLibrary (Lines 184-190)
func GetLockFileItems ¶
func GetLockFileItems(criteria *SelectionCriteria, collection *ContentItemCollection, patternSets ...*PatternSet) []string
GetLockFileItems selects assets using criteria and patterns. Returns paths of items from the best matching group. Reference: LockFileUtils.cs GetLockFileItems (Lines 663-713)
func GetRefItems ¶
func GetRefItems(files []string, targetFramework *frameworks.NuGetFramework, conventions *ManagedCodeConventions) []string
GetRefItems gets compile-time reference assemblies. Tries CompileRefAssemblies first (ref/ folder), then CompileLibAssemblies (lib/ folder) as fallback. Reference: LockFileUtils.cs CreateLockFileTargetLibrary (Lines 177-183)
Types ¶
type CompareTest ¶
CompareTest determines which of two available values is nearer to criterion. Reference: ContentPropertyDefinition.cs CompareTest Returns: -1 if available1 is nearer, 1 if available2 is nearer, 0 if equal
type CompatibilityProfile ¶
type CompatibilityProfile struct {
Name string
RestoreContexts []*FrameworkRuntimePair // Framework + optional RID pairs
}
CompatibilityProfile defines framework/RID combinations for portable apps. Example: "net46.app" profile might support net46 on win/win-x86/win-x64
type CompatibilityTest ¶
CompatibilityTest checks if criterion is compatible with available value. Reference: ContentPropertyDefinition.cs CompatibilityTest
type ContentItem ¶
ContentItem represents a matched path with extracted properties. Reference: ContentModel/ContentItem.cs
func (*ContentItem) Add ¶
func (c *ContentItem) Add(key string, value any)
Add adds or updates a property value.
type ContentItemCollection ¶
type ContentItemCollection struct {
Assets []*ContentItem
}
ContentItemCollection manages package assets and performs selection. Reference: ContentModel/ContentItemCollection.cs
func NewContentItemCollection ¶
func NewContentItemCollection(paths []string) *ContentItemCollection
NewContentItemCollection creates a collection from file paths.
func (*ContentItemCollection) FindBestItemGroup ¶
func (c *ContentItemCollection) FindBestItemGroup(criteria *SelectionCriteria, patternSets ...*PatternSet) *ContentItemGroup
FindBestItemGroup selects the best matching group for criteria. Tries each criteria entry in order, finding the best matching group using property comparison. Reference: ContentItemCollection.cs FindBestItemGroup (Lines 136-241)
func (*ContentItemCollection) PopulateItemGroups ¶
func (c *ContentItemCollection) PopulateItemGroups(patternSet *PatternSet) []*ContentItemGroup
PopulateItemGroups groups assets by their properties. Groups are created by matching assets against group patterns, then items are matched against path patterns. Reference: ContentItemCollection.cs PopulateItemGroups (Lines 84-134)
type ContentItemGroup ¶
type ContentItemGroup struct {
Properties map[string]any
Items []*ContentItem
}
ContentItemGroup represents assets grouped by properties. Reference: ContentModel/ContentItemGroup.cs
type FrameworkRuntimePair ¶
type FrameworkRuntimePair struct {
Framework string // e.g., "net46", "netstandard2.0"
RID string // Empty string means RID-agnostic, otherwise specific RID
}
FrameworkRuntimePair represents a framework with an optional RID. Used in compatibility profiles to define supported combinations.
type LiteralSegment ¶
type LiteralSegment struct {
// contains filtered or unexported fields
}
LiteralSegment matches exact text.
func (*LiteralSegment) TryMatch ¶
func (ls *LiteralSegment) TryMatch(item **ContentItem, path string, properties map[string]*PropertyDefinition, startIndex int) (int, bool)
TryMatch for LiteralSegment
type ManagedCodeConventions ¶
type ManagedCodeConventions struct {
// Properties available for pattern matching
Properties map[string]*PropertyDefinition
// Pattern sets for different asset types
RuntimeAssemblies *PatternSet
CompileRefAssemblies *PatternSet
CompileLibAssemblies *PatternSet
NativeLibraries *PatternSet
ResourceAssemblies *PatternSet
MSBuildFiles *PatternSet
MSBuildMultiTargeting *PatternSet
ContentFiles *PatternSet
ToolsAssemblies *PatternSet
}
ManagedCodeConventions defines standard .NET package conventions. Reference: ContentModel/ManagedCodeConventions.cs
func NewManagedCodeConventions ¶
func NewManagedCodeConventions() *ManagedCodeConventions
NewManagedCodeConventions creates standard managed code conventions. Reference: ManagedCodeConventions constructor
type PatternDefinition ¶
type PatternDefinition struct {
// Pattern is the path template with property placeholders.
// Example: "lib/{tfm}/{assembly}"
// Optional properties end with '?': "lib/{any?}"
Pattern string
// Defaults provides default property values.
// Example: {"tfm": &frameworks.NuGetFramework{...}}
Defaults map[string]any
// Table is the token replacement table.
// Maps property values to replacements (e.g., "any" -> DotNet framework)
Table *PatternTable
// PreserveRawValues indicates whether to preserve unparsed string values.
// Performance optimization for grouping operations.
PreserveRawValues bool
}
PatternDefinition defines a file path pattern with property placeholders. Reference: ContentQueryDefinition.cs PatternDefinition
type PatternExpression ¶
type PatternExpression struct {
// contains filtered or unexported fields
}
PatternExpression is a compiled pattern with optimized matching. Reference: ContentModel/Infrastructure/Parser.cs PatternExpression
func NewPatternExpression ¶
func NewPatternExpression(pattern *PatternDefinition) *PatternExpression
NewPatternExpression compiles a pattern definition into an expression. Reference: PatternExpression constructor
func (*PatternExpression) Match ¶
func (pe *PatternExpression) Match(path string, propertyDefinitions map[string]*PropertyDefinition) *ContentItem
Match attempts to match path against this expression. Reference: PatternExpression.Match
type PatternSet ¶
type PatternSet struct {
// GroupPatterns match directory-level patterns.
// Used for grouping items by common properties.
GroupPatterns []*PatternDefinition
// PathPatterns match individual file paths.
// Used for selecting specific assets.
PathPatterns []*PatternDefinition
// GroupExpressions are compiled group patterns (for performance).
GroupExpressions []*PatternExpression
// PathExpressions are compiled path patterns (for performance).
PathExpressions []*PatternExpression
// PropertyDefinitions available for this pattern set.
PropertyDefinitions map[string]*PropertyDefinition
}
PatternSet groups multiple patterns for a specific asset type. Reference: ContentQueryDefinition.cs PatternSet
func NewPatternSet ¶
func NewPatternSet( properties map[string]*PropertyDefinition, groupPatterns []*PatternDefinition, pathPatterns []*PatternDefinition, ) *PatternSet
NewPatternSet creates a pattern set with compiled expressions.
type PatternTable ¶
type PatternTable struct {
// contains filtered or unexported fields
}
PatternTable is a token replacement table organized by property. Reference: ContentModel/PatternTable.cs
func NewPatternTable ¶
func NewPatternTable(entries []PatternTableEntry) *PatternTable
NewPatternTable creates a pattern table from entries.
type PatternTableEntry ¶
type PatternTableEntry struct {
PropertyName string // Property this entry applies to (e.g., "tfm")
Name string // Token name to replace (e.g., "any")
Value any // Replacement value
}
PatternTableEntry defines a token replacement. Reference: ContentModel/PatternTableEntry.cs
type PropertyDefinition ¶
type PropertyDefinition struct {
// Name is the property identifier (e.g., "tfm", "rid", "assembly")
Name string
// FileExtensions for file-based properties (e.g., [".dll", ".exe"])
FileExtensions []string
// AllowSubFolders allows file extensions to match in subdirectories
AllowSubFolders bool
// Parser converts string value to typed value
Parser PropertyParser
// CompatibilityTest checks if criterion is satisfied by available value
CompatibilityTest CompatibilityTest
// CompareTest finds the nearest candidate
CompareTest CompareTest
}
PropertyDefinition defines how a property is parsed and compared. Reference: ContentModel/ContentPropertyDefinition.cs
func (*PropertyDefinition) Compare ¶
func (pd *PropertyDefinition) Compare(criteriaValue, candidateValue1, candidateValue2 any) int
Compare compares two candidate values against a criterion. Reference: ContentPropertyDefinition.cs Compare
func (*PropertyDefinition) IsCriteriaSatisfied ¶
func (pd *PropertyDefinition) IsCriteriaSatisfied(criteriaValue, candidateValue any) bool
IsCriteriaSatisfied checks if criterion is satisfied by candidate value. Reference: ContentPropertyDefinition.cs IsCriteriaSatisfied
func (*PropertyDefinition) TryLookup ¶
func (pd *PropertyDefinition) TryLookup(name string, table *PatternTable, matchOnly bool) (any, bool)
TryLookup attempts to parse a value using this property definition. Reference: ContentPropertyDefinition.cs TryLookup
type PropertyParser ¶
type PropertyParser func(value string, table *PatternTable, matchOnly bool) any
PropertyParser parses a property value from a string. Reference: ContentPropertyDefinition.cs Parser
Parameters:
- value: substring to parse (no allocation)
- table: pattern table for token replacement
- matchOnly: if true, skip value actualization (performance optimization)
Returns parsed value or nil if doesn't match.
type RuntimeDependencySet ¶
type RuntimeDependencySet struct {
ID string // Package ID that has RID-specific dependencies
Dependencies map[string]*RuntimePackageDependency // Dependency ID -> version constraint
}
RuntimeDependencySet represents RID-specific package dependencies. Example: win10-x64 might require additional native dependencies.
type RuntimeDescription ¶
type RuntimeDescription struct {
RID string
Imports []string // Compatible RIDs (less specific) - JSON key is "#import"
RuntimeDependencies map[string]*RuntimeDependencySet // Package ID -> RID-specific dependencies
}
RuntimeDescription describes a runtime and its compatible runtimes. Reference: NuGet.RuntimeModel/RuntimeDescription.cs
type RuntimeGraph ¶
type RuntimeGraph struct {
// Runtimes maps RID to its description
Runtimes map[string]*RuntimeDescription
// Supports maps profile name to compatibility profiles
// Used for portable app compatibility (e.g., "net46.app" profile)
Supports map[string]*CompatibilityProfile
// contains filtered or unexported fields
}
RuntimeGraph represents the RID compatibility graph. Reference: NuGet.RuntimeModel/RuntimeGraph.cs
func LoadDefaultRuntimeGraph ¶
func LoadDefaultRuntimeGraph() *RuntimeGraph
LoadDefaultRuntimeGraph loads the default .NET RID graph. Reference: https://learn.microsoft.com/en-us/dotnet/core/rid-catalog
func LoadFromJSON ¶
func LoadFromJSON(data []byte) (*RuntimeGraph, error)
LoadFromJSON loads a runtime graph from JSON. Reference: NuGet.Client JsonRuntimeFormat.cs
func NewRuntimeGraph ¶
func NewRuntimeGraph() *RuntimeGraph
NewRuntimeGraph creates an empty runtime graph.
func (*RuntimeGraph) AddRuntime ¶
func (g *RuntimeGraph) AddRuntime(rid string, imports []string)
AddRuntime adds a runtime to the graph.
func (*RuntimeGraph) AreCompatible ¶
func (g *RuntimeGraph) AreCompatible(targetRID, packageRID string) bool
AreCompatible checks if targetRID is compatible with packageRID. Uses cached expansion for performance (NuGet.Client uses ConcurrentDictionary).
func (*RuntimeGraph) ExpandRuntime ¶
func (g *RuntimeGraph) ExpandRuntime(rid string) []string
ExpandRuntime returns all compatible RIDs in priority order (nearest first). Uses BFS traversal to ensure correct ordering for asset selection. Example: win10-x64 expands to [win10-x64, win10, win-x64, win81-x64, win81, ..., win, any, base] Reference: NuGet.Client RuntimeGraph.cs ExpandRuntime
func (*RuntimeGraph) FindRuntimeDependencies ¶
func (g *RuntimeGraph) FindRuntimeDependencies(runtimeName, packageID string) []*RuntimePackageDependency
FindRuntimeDependencies finds RID-specific dependencies for a package. Returns the dependencies for the most specific compatible RID. Reference: NuGet.Client RuntimeGraph.cs FindRuntimeDependencies
func (*RuntimeGraph) GetAllCompatibleRIDs ¶
func (g *RuntimeGraph) GetAllCompatibleRIDs(targetRID string) []string
GetAllCompatibleRIDs returns all RIDs compatible with the target RID. This is a convenience wrapper around ExpandRuntime for clarity.
type RuntimeIdentifier ¶
type RuntimeIdentifier struct {
// RID is the raw RID string
RID string
// OS is the operating system component (e.g., "win", "linux", "osx")
OS string
// Version is the OS version component (e.g., "10.12" in "osx.10.12-x64")
Version string
// Architecture is the architecture component (e.g., "x64", "arm64")
Architecture string
// Qualifiers are additional qualifiers beyond architecture
Qualifiers []string
}
RuntimeIdentifier represents a parsed RID. Reference: NuGet.RuntimeModel/RuntimeDescription.cs
func ParseRID ¶
func ParseRID(rid string) (*RuntimeIdentifier, error)
ParseRID parses a runtime identifier string. Format: <os>.<version>-<architecture>-<qualifiers> Examples: "win10-x64", "linux-x64", "osx.10.12-x64"
func (*RuntimeIdentifier) IsCompatible ¶
func (r *RuntimeIdentifier) IsCompatible(other *RuntimeIdentifier, graph *RuntimeGraph) bool
IsCompatible checks if this RID is compatible with another RID using the graph.
func (*RuntimeIdentifier) String ¶
func (r *RuntimeIdentifier) String() string
String returns the RID string.
type RuntimePackageDependency ¶
type RuntimePackageDependency struct {
ID string
VersionRange string // e.g., "1.0.0", "[1.0.0,2.0.0)"
}
RuntimePackageDependency represents a single RID-specific dependency.
type Segment ¶
type Segment interface {
// TryMatch attempts to match this segment against path.
// Returns true and end index if match succeeds.
TryMatch(item **ContentItem, path string, properties map[string]*PropertyDefinition, startIndex int) (int, bool)
}
Segment represents a pattern segment (literal or token).
type SelectionCriteria ¶
type SelectionCriteria struct {
Entries []SelectionCriteriaEntry
}
SelectionCriteria contains ordered list of criteria entries for asset selection. Entries are tried in order, allowing fallback behavior (e.g., RID-specific → RID-agnostic). Reference: ContentModel/SelectionCriteria.cs
func ForFramework ¶
func ForFramework(framework *frameworks.NuGetFramework, properties map[string]*PropertyDefinition) *SelectionCriteria
ForFramework creates criteria for framework-only matching (no RID). Reference: ManagedCodeConventions.cs ForFramework (Lines 410-417)
func ForFrameworkAndRuntime ¶
func ForFrameworkAndRuntime(framework *frameworks.NuGetFramework, runtimeIdentifier string, properties map[string]*PropertyDefinition) *SelectionCriteria
ForFrameworkAndRuntime creates criteria with RID fallback. First tries RID-specific assets, then falls back to RID-agnostic assets. Reference: ManagedCodeConventions.cs ForFrameworkAndRuntime (Lines 377-405)
type SelectionCriteriaBuilder ¶
type SelectionCriteriaBuilder struct {
// contains filtered or unexported fields
}
SelectionCriteriaBuilder builds selection criteria with fluent API. Reference: ContentModel/SelectionCriteriaBuilder.cs
func NewSelectionCriteriaBuilder ¶
func NewSelectionCriteriaBuilder(properties map[string]*PropertyDefinition) *SelectionCriteriaBuilder
NewSelectionCriteriaBuilder creates a new criteria builder.
func (*SelectionCriteriaBuilder) Add ¶
func (b *SelectionCriteriaBuilder) Add(key string, value any) *SelectionCriteriaBuilder
Add sets a property value and returns builder for chaining.
func (*SelectionCriteriaBuilder) Build ¶
func (b *SelectionCriteriaBuilder) Build() *SelectionCriteria
Build finalizes and returns the criteria.
func (*SelectionCriteriaBuilder) NextEntry ¶
func (b *SelectionCriteriaBuilder) NextEntry() *SelectionCriteriaBuilder
NextEntry finalizes current entry and starts new one.
type SelectionCriteriaEntry ¶
SelectionCriteriaEntry represents a single criteria entry with properties. Reference: ContentModel/SelectionCriteriaEntry.cs
type TokenSegment ¶
type TokenSegment struct {
// contains filtered or unexported fields
}
TokenSegment matches a property placeholder.
func (*TokenSegment) TryMatch ¶
func (ts *TokenSegment) TryMatch(item **ContentItem, path string, properties map[string]*PropertyDefinition, startIndex int) (int, bool)
TryMatch for TokenSegment