Agenda Assemblies 101 Anatomy of an Assembly What is Metadata? Assembly Variations Signing Assemblies Global Assembly Cache

What is an Assembly? Abstract unit of of compiled code Fundamental app building block in.NET Can consist of one or more compiled files Can be an “EXE” or a “DLL” Often called “Logical” DLL

Role of Assemblies Unit of application deployment  Minimal unit of referencable compiled code Provide minimum unit of execution or loading  Minimal unit of self-sufficiency Establish baseline version granularity  All assembly components version together

Role of Assemblies (cont) Establish type definition scope  User defined class/types defined within context of assembly  Declared types unique per assembly Define security permission boundaries  Digital signatures/strong names applied per assembly

Overcoming COM Limitations Not extensible  Assembly “metadata” is infinitely extendable No dependency information  Assembly “Manifest” includes code dependencies No standard type definition format  Assembly type definitions follow CTS Binary machine code = brittle  MSIL based on ECMA-ratified CIL standard

Agenda Assemblies 101 Anatomy of an Assembly Assembly Metadata Assembly Variations Signing Assemblies Global Assembly Cache

Primary Assembly Elements Assembly Manifest  Only requirement to function/qualify as assembly  Includes names and hashes of all files that make up the assembly MSIL Type Metadata*  TYPE or resource info needed for assembly to serve any real purpose Resources*  Type or RESOURCE info needed for assembly to serve any real purpose

“Product” Analogy Manifest => “Assembly” Manual Type Metadata => Product Parts MSIL => Instructional Manual Resources => Packet of misc. stuff to allow product to function  (batteries, velvet/rubber feet, screws, mini-wrench, scorepad, etc)

Assembly Types “Standard” Assembly  Common = Manifest + MSIL + Type Meta  Less Common = Manifest + Type Meta Satellite Assembly  Manifest + resources [+] MSIL Module  Type Meta [+] MSIL [+] resources  Not standalone deployable unit of code  Linked to assembly (multi-file) with AL.exe

Agenda Assemblies 101 Anatomy of an Assembly Assembly Metadata Assembly Variations Signing Assemblies Global Assembly Cache

What is Assembly Metadata? Glue enabling many aspects of assembly functionality Information describing ALL characteristics of an assembly  Exposed types  Security requirements  File dependencies  Developer information (digital signature)

What is the Assembly Manifest? Special section of metadata stored in every assembly  Describes assembly version requirements  Specifies security identity  Define Scope of assembly  Resolve references to resources and classes Describes how the elements in the assembly relate to each other Required set of metadata need for loading the assembly

Location of the Manifest Included in PE file (exe or dll) along with IL Compile standalone (using command-line compiler)

Manifest Function Lists files comprising assembly Lists file dependencies of assembly Maps types and resources to files containing implementation Abstracts actual assembly implementation from consumer Allows assembly to be self-describing and highly portable

Manifest – Assembly Identity Assembly Identity  Assembly name  File name minus extension  Version  Consists of Major.Minor.revision.build numbers  Culture  Information on the culture or language the assembly supports  Strong name info  Involves public key and strong name concepts

Manifest – File References List of files comprising assembly  A name and hash of each file  All assembly files must be in the same directory as the manifest Information on Referenced Assemblies  A list of statically referenced assemblies  Includes dependent assembly’s details  Identity  Metadata  Public key (if strongly named)

Manifest – Types Type Reference Information  Allows mapping of types to actual files with type implementation  Used for types that are exported from the assembly  Provides self-description capabilities

Agenda Assemblies 101 Anatomy of an Assembly Explaining Assembly Metadata Assembly Variations Signing Assemblies Global Assembly Cache

Single file Assembly Most common (and simplest) form of assembly Either class library (DLL) or application (EXE) When accessed from app dir, does not undergo version checking Fully portable  If Fx installed on system, no additional files needed

Single file Assembly Contents Assembly Manifest Type Metadata MSIL code Resources

Building a Single-File Assembly

Multi-file Assembly Involves multiple files compiled into modules C# or VB.NET must use command-line compiler to create modules  Managed C++ can use VS.NET Modules can be resources and/or code Files not explicitly linked by file system  Files managed as a unit by CLR

Multi-file Considerations Files require same version  Version is maintained per assembly, not individual file Model of deployment  Optimize downloading Reuse  Resources/code used by multiple apps Type Scope  Limit type visibility to assembly

Multi-file Assembly Contents Assembly Manifest Type Metadata MSIL code Resources

Multi Versus Single File Combine different language modules  For localizing applicatons Optimize application download  Using with IE or Assembly.LoadFrom to download assemblies  Seldom used types can DL module on demand Team development  Different developers work on different modules  Maintain version synchronization

Creating a Multi-file Assembly Step 1: Compile (into modules) code files containing referenced namespaces  Example: CodeB.cs contains namespace referenced by CodeA.cs – Compile CodeB first Step 2: Compile remaining modules used by assembly  Use /addmodule switch of vbc.exe or csc.exe to reference module types Step 3: Use Assembly Linker (AL.exe) to stitch assembly together  Creates output file serving as application executable

Building a Multi-file Assembly

Agenda Assemblies 101 Anatomy of an Assembly Explaining Assembly Metadata Assembly Variations Signing Assemblies Global Assembly Cache

What is a Strong Name? A combination of assembly information guaranteed to be unique.NET replacement for GUIDs in COM Not a requirement in most cases unless..  Assembly referenced by another strong named assembly  Assembly uses EnterpriseServices  Assembly to be install in the Global Assembly Cache

What does a Strong Name Do? Ensure assembly name is globally unique  Relies on unique key pairs  Assembly signed with Key A has different name than one sign with Key B Protect version lineage  3 rd party can not produce new version of your assembly Provides a strong integrity check  Contents unchanged since being built  Dependent files are also unchanged

How to Sign an Assembly Step 1:  Use SN.exe to generate a key pair Step 2a (IDE):  (Single file) Use the AssemblyKeyFile attribute to assign a key Step 2b (CMD):  (Single-file) Use the /keyfile switch of compiler Step 2c (CMD):  (Multi-file) Use the /keyfile switch of AL.exe to assign the public key

Signing An Assembly

Agenda Assemblies 101 Anatomy of an Assembly Explaining Assembly Metadata Assembly Variations Signing Assemblies Global Assembly Cache

What is the GAC? Machine-wide code cache Special system folder  \assembly  \GAC for non pre-JITed assemblies  \NativeImages1_v1.0.xxxx for Native assemblies Storage location for assemblies stored and accessible system-wide Supercedes concept of Registry/GUID with COM objects

Installing Into the GAC Use installer designed to work with the GAC  Deployment projects (Windows Installer)  Preferred method, and built into VS.NET Use the Global Assembly Cache Tool (gacutil.exe)  Should be limited to development/testing Use Windows Explorer to drag and drop into the assembly directory  Should be limited to develop/testing

Adding to the GAC

Recommendations Use GAC only when necessary  Ongoing debate, how much should GAC be emphasized  Generally, keep assembly dependencies private and locate in app directory Shared location for use by multiple applications Side by side versioning when assembly file name must be same

Recommendations (cont) Additional search location – GAC checked before probing app directory or using explicit codebase Reason not to  When using xcopy deployment  When using filename different from the assemblyname  Dynamic downloading of assemblies (Assembly.LoadFrom) (UNLESS using as a backup)  When simplicity is a high priority

Agenda Assemblies 101 Anatomy of an Assembly Explaining Assembly Metadata Assembly Variations Signing Assemblies Global Assembly Cache

SDK Assembly Tools Assembly Cache Viewer (Shfusion.dll)  Shell extension allowing drag and drop into GAC Assembly Linker (Al.exe)  Create multi-file assemblies and sign assemblies Assembly Registration Tool (Regasm.exe)  Registers assemblies for use by COM clients Assembly Binding Log Viewer (Fuslogvw.exe)  Displays details for failed assembly binds

SDK Assembly Tools (cont) Global Assembly Cache Tool (Gacutil.exe)  Command-line tool to view and manipulate the GAC Native Image Generator (Ngen.exe)  Pre-JITs assembly to create a native code compiled version and places it.NET Framework Configuration Tool (Mscorcfg.msc)  MMC console for manipulating GAC, security policies, and system configuration.

Session Summary Unit of deployment for compiled code Completely self-describing Can be single or multi-file Can be signed for uniqueness Several SDK Tools available