Module metadata 

.NET metadata parsing, loading, and type system based on ECMA-335.

This module implements the complete ECMA-335 metadata system for .NET assemblies. It provides comprehensive parsing and access to all metadata tables, streams, and type system constructs defined in the Common Language Infrastructure specification.

Architecture

The metadata system is organized into several layers:

• Physical Layer: Raw binary data access and stream parsing
• Logical Layer: Structured access to metadata tables and heaps
• Type System Layer: High-level representation of .NET types and signatures
• Validation Layer: Configurable validation and integrity checking

Key Components

Assembly Analysis

• crate::CilObject - Main entry point for assembly analysis
• crate::metadata::cor20header - CLR 2.0 header information
• crate::metadata::root - Metadata root and stream directory

Type System

• crate::metadata::typesystem - Complete .NET type system representation
• crate::metadata::signatures - Method and field signatures, generics support
• crate::metadata::token - Metadata tokens for cross-references

Method Body Analysis

• crate::metadata::method - Method body parsing and analysis

Metadata Streams

• crate::metadata::streams - All ECMA-335 metadata tables and heaps
• crate::Strings, crate::Guid, crate::Blob, crate::UserStrings - String, GUID, Blob, and UserString heaps
• crate::TablesHeader, crate::StreamHeader - Metadata tables and stream headers

Metadata Tables

• crate::metadata::tables - Assembly, Type, Method, Field, and other metadata tables

Import/Export Analysis

• crate::metadata::imports - Analysis of imported types and methods
• crate::metadata::exports - Analysis of exported types and methods
• crate::metadata::resources - Embedded resources and manifests

Security and Identity

• crate::metadata::security - Code Access Security (CAS) permissions
• crate::metadata::identity - Assembly identity and verification
• crate::metadata::marshalling - P/Invoke and COM interop marshalling

Usage Examples

use dotscope::CilObject;
use std::path::Path;

// Load assembly and examine metadata
let assembly = CilObject::from_path(Path::new("tests/samples/WindowsBase.dll"))?;

// Access basic information
if let Some(module) = assembly.module() {
    println!("Module: {}", module.name);
}

// Examine metadata tables
if let Some(tables) = assembly.tables() {
    println!("Tables present: {}", tables.table_count());
}

// Access type system
let methods = assembly.methods();
println!("Methods found: {}", methods.len());

Integration

The metadata system provides the foundation for the disassembler module, supplying token resolution, type information, and method body access for comprehensive analysis.

Thread Safety

All metadata types are std::marker::Send and std::marker::Sync for safe concurrent access. Metadata parsing and representation for .NET assemblies.

This module contains the core metadata parsing infrastructure for .NET PE files, providing comprehensive support for parsing metadata tables, streams, type systems, and IL code according to the ECMA-335 standard. It serves as the foundation for all .NET assembly analysis capabilities in dotscope.

Architecture Overview

The metadata system is organized into several interconnected layers:

Core Assembly Representation

• Assembly Loading: crate::metadata::cilobject provides the main crate::metadata::cilobject::CilObject type for loaded assemblies
• PE Structure: crate::metadata::cor20header handles the .NET-specific PE header information
• Root Metadata: crate::metadata::root manages the fundamental metadata directory structure

Type System and Signatures

• Type Resolution: crate::metadata::typesystem provides complete .NET type system representation
• Signature Parsing: crate::metadata::signatures handles method and type signature decoding
• Token Management: crate::metadata::token provides metadata table row reference system

Method and Code Analysis

• Method Representation: crate::metadata::method offers comprehensive method analysis with IL disassembly
• Custom Attributes: crate::metadata::customattributes handles .NET attribute parsing and representation
• Security Model: crate::metadata::security implements .NET declarative security parsing

Metadata Streams and Tables

• Stream Management: crate::metadata::streams handles all metadata heap types (strings, blobs, GUIDs, user strings)
• Table Processing: crate::metadata::tables provides access to all ECMA-335 metadata tables
• Data Loading: Internal loader implements the metadata loading and caching infrastructure

Interoperability and Resources

• P/Invoke Support: crate::metadata::imports and crate::metadata::exports handle native code interop
• Type Marshalling: crate::metadata::marshalling manages native type conversion specifications
• Resource Access: crate::metadata::resources provides .NET resource extraction and parsing

Quality and Validation

• Assembly Verification: crate::metadata::identity handles strong name and authenticode validation
• Metadata Validation: crate::metadata::validation provides comprehensive metadata consistency checking

Key Components

Primary Assembly Interface

• crate::metadata::cilobject::CilObject - Main assembly representation with metadata and IL code
• crate::metadata::method::Method - Complete method analysis with IL disassembly and control flow
• crate::metadata::typesystem::TypeRegistry - Comprehensive .NET type system representation

Core Infrastructure

• crate::metadata::token::Token - Metadata table row references used throughout .NET
• crate::metadata::signatures - Method and type signature parsing infrastructure
• crate::metadata::streams - Metadata stream parsing (strings, blobs, GUIDs, etc.)

Usage Patterns

Basic Assembly Loading and Analysis

use dotscope::CilObject;
use std::path::Path;

// Load and parse a .NET assembly
let assembly = CilObject::from_path(Path::new("tests/samples/WindowsBase.dll"))?;

// Access basic assembly information
if let Some(assembly_info) = assembly.assembly() {
    println!("Assembly: {} (Version: {}.{})",
             assembly_info.name, assembly_info.major_version, assembly_info.minor_version);
}

// Get counts of major metadata elements
println!("Methods: {}", assembly.methods().len());
println!("Types: {}", assembly.types().len());
if let Some(module) = assembly.module() {
    println!("Module name: {}", module.name);
}

Method Analysis and IL Code Inspection

use dotscope::CilObject;
use std::path::Path;

let assembly = CilObject::from_path(Path::new("tests/samples/WindowsBase.dll"))?;

// Analyze methods with IL code
for entry in assembly.methods().iter().take(10) {
    let method = entry.value();
     
    if method.instruction_count() > 0 {
        println!("Method: {} ({} instructions)",
                 method.name, method.instruction_count());
         
        // Examine method characteristics
        if method.flags_modifiers.contains(
            dotscope::metadata::method::MethodModifiers::VIRTUAL) {
            println!("  - Virtual method");
        }
         
        if method.flags_modifiers.contains(
            dotscope::metadata::method::MethodModifiers::STATIC) {
            println!("  - Static method");
        }
    }
}

Type System Exploration

use dotscope::CilObject;
use std::path::Path;

let assembly = CilObject::from_path(Path::new("tests/samples/WindowsBase.dll"))?;

// Explore the type system
for entry in assembly.types().iter().take(10) {
    let type_def = entry.value();
     
    println!("Type: {} (Namespace: {})",
             type_def.name, type_def.namespace);
     
    // Show type characteristics using flags
    if type_def.flags_visibility.contains(TypeVisibility::PUBLIC) {
        println!("  - Public visibility");
    }
     
    if type_def.flags_layout.contains(TypeLayout::ABSTRACT) {
        println!("  - Abstract type");
    }
     
    if type_def.flags_layout.contains(TypeLayout::SEALED) {
        println!("  - Sealed type");
    }
     
    println!("  - {} methods, {} fields",
             type_def.methods.len(), type_def.fields.len());
}

Thread Safety

All metadata types are designed for safe concurrent access:

• Immutable Data: Most metadata structures are read-only after parsing
• Arc-based Sharing: Reference counting enables safe multi-threaded access
• Lazy Initialization: OnceLock ensures thread-safe lazy loading

Error Handling

The metadata system provides comprehensive error handling for malformed assemblies:

• Format Validation: ECMA-335 compliance checking
• Bounds Checking: Safe access to all metadata structures
• Graceful Degradation: Partial parsing when possible
• Detailed Diagnostics: Clear error messages for debugging

References

• ECMA-335 6th Edition - Common Language Infrastructure (CLI)
• Microsoft .NET Framework PE Format Specification
• Windows PE/COFF Specification

Modules

cilassemblyview

Implementation of a raw assembly view for editing operations Raw assembly view for editing and modification operations.

cilobject

Implementation of a loaded + parsed CIL binary High-level .NET assembly abstraction and metadata access.

cor20header

Implementation of the Header of CIL CLR 2.0 (Cor20) header parsing for .NET assemblies.

customattributes

Implementation of custom attribute parsing and representation Custom attribute parsing and representation for .NET metadata.

customdebuginformation

Implementation of custom debug information parsing for Portable PDB format Custom debug information parsing for Portable PDB format.

dependencies

Multi-assembly dependency tracking and analysis system Multi-assembly dependency tracking and analysis system.

diagnostics

Diagnostics collection for assembly loading and analysis Diagnostics collection for assembly loading and analysis.

exports

Implementation of ‘Exports’ by the loaded binary Analysis and representation of exported types in .NET assemblies.

identity

Assembly identity and cryptographic verification system Assembly identity and cryptographic verification for .NET assemblies.

imports

Implementation of methods that are imported from other binaries (native or .net) Analysis and representation of imported types and methods in .NET assemblies.

importscope

Implementation of import scope parsing for Portable PDB format Import scope parsing and representation for Portable PDB debugging metadata.

marshalling

Implementation of the type marshalling for native code invokations Type marshalling for native code invocations and COM interop in .NET assemblies.

method

Implementation of the MethodHeader of CIL Method representation and analysis for .NET assemblies.

query

Composable query system for types and methods Composable query system for types and methods.

resources

Implementation of the .NET resources Embedded resources and manifest resource management for .NET assemblies.

root

Implementation of the root metadata structure Metadata root header and stream directory for .NET assemblies.

security

Implementation of the .NET security model .NET Code Access Security (CAS) implementation.

sequencepoints

Implementation of sequence points in methods

signatures

Implementation of method and type signatures Method and type signature parsing for .NET metadata according to ECMA-335.

streams

Implementation of all metadata streams (tables, heaps, etc.) ECMA-335 Metadata Streams for .NET Assembly Processing

tablefields

Table field layout definitions for heap references Table field layout definitions for heap references.

tables

Implementation of the .NET metadata tables

token

Commonly used metadata token type Metadata token implementation for .NET assembly analysis.

typesystem

Implementation of the .NET type system .NET type system implementation for CIL analysis.

validation

Metadata validation utilities Metadata validation system for .NET assemblies.