52. EPMO Open Source Coordination Office Redaction File Detail Report

Produced by Araxis Merge on 6/22/2018 1:25:52 PM Central Daylight Time. See www.araxis.com for information about Merge. This report uses XHTML and CSS2, and is best viewed with a modern standards-compliant browser. For optimum results when printing this report, use landscape orientation and enable printing of background images and colours in your browser.

52.1 Files compared

#	Location	File	Last Modified
1	v1603_release_60.zip\Assemblies\VA.FTP2.Plugins\packages\ilmerge.2.13.0307	ILMerge.doc	Tue Jun 5 16:24:07 2018 UTC
2	v1603_release_60.zip\Assemblies\VA.FTP2.Plugins\packages\ilmerge.2.13.0307	ILMerge.doc	Fri Jun 22 14:02:22 2018 UTC

52.2 Comparison summary

Description	Between Files 1 and 2
Description	Text Blocks	Lines
Unchanged	1	314
Changed	1	2
Inserted	0	0
Removed	0	0

52.3 Comparison options

Whitespace
Character case	Differences in character case are significant
Line endings	Differences in line endings (`CR` and `LF` characters) are ignored
CR/LF characters	Not shown in the comparison detail

52.4 Active regular expressions

No regular expressions were active.

52.5 Comparison detail

	1	ILMerge
	2	Michael Ba rnett
	3	Programmin g Language s and Meth ods
	4	Microsoft Research
	5	Copyright (C) Micros oft Corpor ation. All rights re served.
	6	Introducti on
	7	This docum ent descri bes the IL Merge util ity which merges mul tiple .NET assemblie s into a s ingle asse mbly. Howe ver, some .NET assem blies may not be abl e to be me rged becau se they ma y contain features s uch as unm anaged cod e. I would highly re commend us ing peveri fy (the .N ET Framewo rk SDK too l) on the output of ILMerge to guarantee that the output is verifiable and will load in th e .NET run time.
	8	ILMerge is packaged as a conso le applica tion. But all of its functiona lity is al so accessi ble progra mmatically . Note tha t Visual S tudio does allow one to add an executabl e as a ref erence, so you can w rite a cli ent that u ses ILMerg e as a lib rary.
	9	ILMerge ta kes a set of input a ssemblies and merges them into one targe t assembly . The firs t assembly in the li st of inpu t assembli es is the primary as sembly. Wh en the pri mary assem bly is an executable , then the target as sembly is created as an execut able with the same e ntry point as the pr imary asse mbly. Also , if the p rimary ass embly has a strong n ame, and a .snk file is provid ed, then t he target assembly i s re-signe d with the specified key so th at it also has a str ong name.
	10	Note that anything t hat depend ed upon an y of the n ames of th e input as semblies, e.g., conf iguration files, mus t be updat ed to refe r instead to the nam e of the t arget asse mbly.
	11	Any Win32 Resources in the pri mary assem bly are co pied over into the t arget asse mbly.
	12	There are many optio ns that co ntrol the behavior o f ILMerge. These are described in the ne xt section .
	13	Public Int erface
	14	The public interface for ILMer ge is defi ned in the ILMerging namespace as the cl ass ILMerg e.
	15	namespace ILMerging;
	16	public cla ss ILMerge { }
	17	To use thi s class pr ogrammatic ally, just create an instance using the default (n ullary) co nstructor. There are several p roperties and method s which ar e used to affect the behavior of the mer ging. The method Mer ge() is ca lled to ac tually per form the m erging.
	18	AllowDupli cateType
	19	public voi d AllowDup licateType (string ty peName);
	20	The normal behavior of ILMerge is to not allow the re to be m ore than o ne public type with the same n ame. If su ch a dupli cate is fo und, then an excepti on is thro wn. Howeve r, ILMerge can just rename the type so t hat it no longer cau ses a conf lict. For private ty pes, this is not a p roblem sin ce no outs ide client can see i t anyway, so ILMerge just does the renam ing by def ault. For public typ es, it is not often a useful f eature to have it re named. How ever, ther e are situ ations whe re it is n eeded. In particular , for obfu scated ass emblies, i t seems th at the obf uscator de fines an a ttribute a nd creates an assemb ly-level a ttribute f or the obf uscated as sembly usi ng that at tribute. T his would mean that obfuscated assemblie s cannot b e merged.
	21	So this op tion allow s the user to either allow all public ty pes to be renamed wh en they ar e duplicat es, or to specify it for arbit rary type names. On the comman d line, th ere can be as many o ptions as desired, i f followed by a colo n and a ty pe name, o therwise j ust specif y it alone with no c olon (and type name) to allow all duplic ates.
	22	When used through th e API, an argument o f “null” m eans to al low all pu blic types to be ren amed.
	23	Default: n o duplicat es of publ ic types a llowed
	24	Command li ne option: [/allowDu p[:typeNam e]]*
	25	AllowMulti pleAssembl yLevelAttr ibutes
	26	public boo l AllowMul tipleAssem blyLevelAt tributes { get; set; }
	27	When this is set bef ore callin g Merge, t hen if the CopyAttri butes prop erty (Sect ion 2.7) i s also set , any asse mbly-level attribute s names th at have th e same typ e are copi ed over in to the tar get direct ory as lon g as the d efinition of the att ribute typ e specifie s that “Al lowMultipl e” is true .
	28	Default: f alse
	29	Command li ne option: /allowMul tiple
	30	AllowWildC ards
	31	public boo l AllowWil dCards { g et; set; }
	32	When this is set bef ore callin g Merge, a ny wild ca rds in fil e names ar e expanded and all m atching fi les will b e used as input. Not e that bec ause the w ild card m atching is done by a call to D irectory.G etFiles, i t does not allow the character s ".." to appear in a file nam e. So if y ou want to specify a relative path conta ining ".." to move u p a direct ory, you w ill have t o use it w ith the "/ lib" optio n (Section 2.20). Th at option does allow the use o f ".." to move up di rectories.
	33	Default: f alse
	34	Command li ne option: /wildcard s
	35	AllowZeroP eKind
	36	public boo l AllowZer oPeKind { get; set; }
	37	When this is set bef ore callin g Merge, t hen if an assembly's PeKind fl ag (this i s the valu e of the f ield liste d as .corf lags in th e Manifest ) is zero it will be treated a s if it wa s ILonly. This can b e used to allow C++ assemblies to be mer ged; it do es not app ear that t he C++ com piler writ es the val ue as ILon ly. Howeve r, if such an assemb ly has any non-IL fe atures, th en they wi ll probabl y not be c opied over into the target ass embly corr ectly. So please use this opti on with ca ution.
	38	Default: f alse
	39	Command li ne option: /zeroPeKi nd
	40	AttributeF ile
	41	public str ing Attrib uteFile { get; set; }
	42	If this is set befor e calling Merge, the n it speci fies the p ath and fi lename to an atttrib ute assemb ly, an ass embly that will be u sed to get all of th e assembly -level att ributes su ch as Cult ure, Versi on, etc. I t will als o be used to get the Win32 Res ources fro m. It is m utually ex clusive wi th the Cop yAttribute s property (Section 2.7). When it is not specified , then the Win32 Res ources fro m the prim ary assemb ly are cop ied over i nto the ta rget assem bly. If it is not a full path, then the current di rectory is used.
	43	Default: n ull
	44	Command li ne option: /attr:fil ename
	45	Closed
	46	public boo l Closed { get; set; }
	47	When this is set bef ore callin g Merge, t hen the "t ransitive closure" o f the inpu t assembli es is comp uted and a dded to th e list of input asse mblies. An assembly is conside red part o f the tran sitive clo sure if it is refere nced, eith er directl y or indir ectly, fro m one of t he origina lly specif ied input assemblies and it ha s an exter nal refere nce to one of the in put assemb lies, or o ne of the assemblies that has such a ref erence. Co mplicated, but that is life...
	48	Default: f alse
	49	Command li ne option: /closed
	50	CopyAttrib utes
	51	public boo l CopyAttr ibutes { g et; set; }
	52	When this is set bef ore callin g Merge, t hen the as sembly lev el attribu tes of eac h input as sembly are copied ov er into th e target a ssembly. A ny duplica te attribu te overwri tes a prev iously cop ied attrib ute. If yo u want to allow dupl icates (fo r those at tributes w hose type specifies “AllowMult iple” in t heir defin ition), th en you can also set the AllowM ultipleAss emblyLevel Attributes (Section 2.2). The input asse mblies are processed in the or der they a re specifi ed. This o ption is m utually ex clusive wi th specify ing an att ribute ass embly, i.e ., the pro perty Attr ibuteFile (Section 2 .5). When an attribu te assembl y is speci fied, then no assemb ly-level a ttributes are copied over from the input assemblie s.
	53	Default: f alse
	54	Command li ne option: /copyattr s
	55	DebugInfo
	56	public boo l DebugInf o { get; s et; }
	57	When this is set to true, ILMe rge create s a .pdb f ile for th e output a ssembly an d merges i nto it any .pdb file s found fo r input as semblies. If you do not want a .pdb fil e created for the ou tput assem bly, eithe r set this property to false o r else spe cify the / ndebug opt ion at the command l ine.
	58	Default: t rue
	59	Command li ne option: /ndebug
	60	DelaySign
	61	public boo l DelaySig n { get; s et; }
	62	When this is set bef ore callin g Merge, t hen the ta rget assem bly will b e delay si gned. This can be se t only in conjunctio n with the /keyfile option (Se ction 2.13 ).
	63	Default: f alse
	64	ExcludeFil e
	65	public str ing Exclud eFile { ge t; set; }
	66	This prope rty is use d only in conjunctio n with the Internali ze propert y (Section 2.12). Wh en this is set befor e calling Merge, it indicates the path a nd filenam e that wil l be used to identif y types th at are not to have t heir visib ility modi fied. If I nternalize is true, but Exclud eFile is " ", then al l types in any assem bly other than the p rimary ass embly are made non-p ublic. Set ting this property i mplicitly sets Inter nalize to true.
	67	The conten ts of the file shoul d be one r egular exp ression pe r line. Th e syntax i s that def ined in th e .NET nam espace Sys tem.Text.R egularExpr essions fo r regular expression s. The reg ular expre ssions are matched a gainst eac h type's f ull name, e.g., "Sys tem.Collec tions.ILis t". If the match fai ls, it is tried agai n with the assembly name (surr ounded by square bra ckets) pre pended to the type n ame. Thus, the patte rn “\[A\]. *” exclude s all type s in assem bly A from being mad e non-publ ic. (The b ackslashes are requi red becaus e the stri ng is trea ted as a r egular exp ression.) The patter n “N.T” wi ll match a ll types n amed T in the namesp ace named N no matte r what ass embly they are defin ed in.
	68	It is impo rtant to n ote that t he regular expressio ns are not anchored to the beg inning of the string ; if this is desired , use the appropriat e regular expression operator characters to do so.
	69	Default: " "
	70	Command li ne option: /internal ize[:exclu deFile]
	71	FileAlignm ent
	72	public int FileAlign ment { get ; set; }
	73	This contr ols the fi le alignme nt used fo r the targ et assembl y. The set ter sets t he value t o the larg est power of two tha t is no la rger than the suppli ed argumen t, and is at least 5 12.
	74	Default: 5 12
	75	Command li ne option: /align:n
	76	Internaliz e
	77	public boo l Internal ize { get; set; }
	78	This contr ols whethe r types in assemblie s other th an the pri mary assem bly have t heir visib ility modi fied. When it is tru e, then al l non-exem pt types t hat are vi sible outs ide of the ir assembl y have the ir visibil ity modifi ed so that they are not visibl e from out side of th e merged a ssembly. A type is e xempt if i ts full na me matches a line fr om the Exc ludeFile ( Section 2. 10) using the .NET r egular exp ression en gine.
	79	Default: f alse
	80	Command li ne option: /internal ize[:exclu deFile]
	81	KeyFile
	82	public str ing KeyFil e { get; s et; }
	83	When this is set bef ore callin g Merge, i t specifie s the path and filen ame to a . snk file. The target assembly will be si gned with its conten ts and wil l then hav e a strong name. It can be use d with the DelaySign property (Section 2 .9) to hav e the targ et assembl y delay si gned. This can be do ne even if the prima ry assembl y was full y signed.
	84	Default: n ull
	85	Command li ne option: /keyfile: filename
	86	Log
	87	public boo l Log { ge t; set; }
	88	When this is set bef ore callin g Merge, t hen log me ssages are written. It is used in conjun ction with the LogFi le propert y. If Log is true, b ut LogFile is null, then log m essages ar e written to Console .Out. To s pecify thi s behavior on the co mmand line , the opti on "/log" can be giv en without a log fil e.
	89	Default: f alse
	90	Command li ne option: /log[:log file]
	91	LogFile
	92	public str ing LogFil e { get; s et; }
	93	When this is set bef ore callin g Merge, i t indicate s the path and filen ame that l og message s are writ ten to. If Log is tr ue, but Lo gFile is n ull, then log messag es are wri tten to Co nsole.Out.
	94	Default: n ull
	95	Command li ne option: /log[:log file]
	96	Merge
	97	public voi d Merge();
	98	Once all d esired opt ions are s et, this m ethod perf orms the a ctual merg ing.
	99	OutputFile
	100	public str ing Output File { get ; set; }
	101	This must be set bef ore callin g Merge. I t specifie s the path and filen ame that t he target assembly w ill be wri tten to.
	102	Default: n ull
	103	Command li ne option: /out:file name
	104	PublicKeyT okens
	105	public boo l PublicKe yTokens { get; set; }
	106	This must be set bef ore callin g Merge. I t indicate s whether external a ssembly re ferences i n the mani fest of th e target a ssembly wi ll use ful l public k eys (false ) or publi c key toke ns (true).
	107	Default: t rue
	108	Command li ne option: /useFullP ublicKeyFo rReference s
	109	SetInputAs semblies
	110	public voi d SetInput Assemblies (string[] assems);
	111	When used programmat ically, ea ch element of the ar ray should contain t he path an d filename of an inp ut assembl y. The fir st element of the ar ray is con sidered to be the pr imary asse mbly.
	112	SetSearchD irectories
	113	public voi d SetSearc hDirectori es(string[ ] dirs);
	114	If specifi ed, this s ets the di rectories to be used to search for input assemblie s. When us ed program matically, each elem ent of the array sho uld contai n a direct ory name. When speci fied on th e command line, use a separate "/lib" op tion for e ach direct ory.
	115	Command li ne option: /lib:dire ctory
	116	SetTargetP latform
	117	public voi d SetTarge tPlatform( string pla tform, str ing dir);
	118	This metho d sets the .NET Fram ework for the target assembly to be the one specif ied by pla tform. Val id strings for the f irst argum ent are "v 1", "v1.1" , "v2", an d "v4". Th e "v" is c ase insens itive and is also op tional. Th is way ILM erge can b e used to "cross-com pile", i.e ., it can run in one version o f the fram ework and generate t he target assembly s o it will run under a differen t assembly . The seco nd argumen t is the d irectory i n which ms corlib.dll is to be found.
	119	Command li ne option: /targetpl atform:ver sion,platf ormdirecto ry
	120	StrongName Lost
	121	public boo l StrongNa meLost { g et; }
	122	Once mergi ng is comp lete, this property is true if and only if the pri mary assem bly had a strong nam e, but the target as sembly doe s not. Thi s can occu r when an .snk file is not spe cified, or if someth ing goes w rong tryin g to read its conten ts.
	123	TargetKind
	124	public ILM erge.Kind { get; set ; }
	125	This contr ols whethe r the targ et assembl y is creat ed as a li brary, a c onsole app lication o r as a Win dows appli cation. Wh en it is n ot specifi ed, then t he target assembly w ill be the same kind as that o f the prim ary assemb ly. (In th at case, t he file ex tensions f ound on th e specifie d target a ssembly an d the prim ary assemb ly must ma tch.) When it is spe cified, th en the fil e extensio n of the t arget asse mbly must match the specificat ion.
	126	The possib le values are ILMerg e.Kind.{Dl l, Exe, Wi nExe}
	127	Default: I LMerge.Kin d.SameAsPr imaryAssem bly
	128	Command li ne option: /target:( library\|ex e\|winexe)
	129	UnionMerge
	130	public boo l { get; s et; }
	131	When this is true, t hen types with the s ame name a re all mer ged into a single ty pe in the target ass embly. The single ty pe is the union of a ll of the individual types in the input assemblies : it conta ins all of the membe rs from ea ch of the correspond ing types in the inp ut assembl ies. It ca nnot be sp ecified at the same time as /a llowDup.
	132	Default: f alse
	133	Command li ne option: /union
	134	Version
	135	public Sys tem.Versio n Version { get; set ; }
	136	When this has a non- null value , then the target as sembly wil l be given its value as the ve rsion numb er of the assembly. When speci fied on th e command line, the version is read in a s a string and shoul d look lik e "6.2.1.3 " (but wit hout the q uote marks ). The ver sion must be a valid assembly version as defined b y the attr ibute Asse mblyVersio n in the S ystem.Refl ection nam espace.
	137	Default: n ull
	138	Command li ne option: /ver:vers ion
	139	XmlDocumen tation
	140	public boo l XmlDocum entation { get; set; }
	141	This prope rty contro ls whether XML docum entation f iles are m erged to p roduce an XML docume ntation fi le for the target as sembly.
	142	Default: f alse
	143	Command li ne option: /xmldocs
	144	Command Li ne Usage
	145	The full c ommand lin e for ILMe rge is:
	146	ilmerge [/ lib:direct ory]* [/lo g[:filenam e]] [/keyf ile:filena me [/delay sign]] [/i nternalize [:filename ]] [/t[arg et]:(libra ry\|exe\|win exe)] [/cl osed] [/nd ebug] [/ve r:version] [/copyatt rs [/allow Multiple]] [/xmldocs ] [/attr:f ilename] ( [/targetpl atform:<ve rsion>[,<p latformdir >]]\|v1\|v1. 1\|v2\|v4) [ /useFullPu blicKeyFor References ] [/zeroPe Kind] [/wi ldcards] [ /allowDup[ :typename] ]* [/allow DuplicateR esources] [/union] [ /align:n] /out:filen ame <prima ry assembl y> [<other assemblie s>...]
	147	All optio ns that ta ke argumen ts can use either ": " or "=" a s a separa tor. Optio ns can be in any ord er, but al l of the o ptions mus t precede the list o f input as semblies.
	148	Troublesho oting
	149	Input asse mbly not m erged in c orrectly
	150	A common p roblem is that after merging s ome assemb lies, you get an err or message stating t hat an inp ut assembl y was not merged in correctly because it is still listed as an externa l referenc e in the m erged asse mbly. The most commo n cause of this prob lem is tha t one of t he input a ssemblies, B, has an external reference to the inc orrectly m erged asse mbly, A, a nd also an external reference to another assembly, C, that i tself has an externa l referenc e to A. Su ppose the reference to C is to a method that takes an argume nt whose t ype is def ined in A. Then the type signa ture of th e method c all to the method in C still r efers to t he type fr om A even in the mer ged assemb ly. After all, ILMer ge cannot go and mod ify the as sembly C s o that it now depend s on the t ype as it is defined in the ou tput assem bly after it has bee n merged!
	151	The soluti on is to u se the clo sed option (Section 2.6) to ha ve ILMerge compute t he transit ive closur e of the i nput assem blies to p revent thi s kind of “dangling reference” . In the e xample, th at would r esult in a ll three a ssemblies A, B, and C, being m erged. The re is no w ay to merg e just A a nd B witho ut there s till being an extern al referen ce to A.
	152	Merged ass embly caus es a runti me error ( not presen t in the u nmerged as semblies)
	153	The most f requent ca use of pro blems when executing the targe t assembly is that I LMerge has no way to merge res ources. Th erefore re sources ar e just cop ied over f rom the in put assemb lies into the target assembly. If these resources encode ref erences to types def ined in th e input as semblies, then at ru ntime your program m ay fail be cause the type retur ned from t he resourc e does not match the type as i t is defin ed in the target ass embly. You may even see a mess age that “ type ‘T’ c annot be c onverted t o type ‘T’ ”. This lo oks confus ing becaus e the mess ages do no t show the assembly that each type is de fined in. The actual error is that one t ype is def ined in th e input as sembly whi le the oth er is defi ned in the target as sembly.
	154	I do not k now of any way to ha ve ILMerge do the ri ght thing in such ca ses. There is no gen eral way t o decode r esources a nd change any type r eferences they conta in.
	155	Dependenci es
	156	ILMerge is a stand-a lone assem bly depend ent only o n the v2.0 .NET Fram ework. (It actually uses two o ther assem blies: the assembly that makes up CCI it self, Syst em.Compile r.dll, and AssemblyR esolver.dl l, which p rovides a small comp onent for finding an d loading assemblies when requ ested by t he CCI Rea der. But t hose assem blies have been merg ed into IL Merge usin g ILMerge before it is distrib uted.
	157	Acknowledg ements
	158	Without He rman Vente r, this to ol could n ot have be en written . Not only because i t complete ly depends on CCI to provide t he underly ing functi onality fo r reading, transform ing, and w riting IL, but becau se of all of his hel p and supp ort.