From f5734c74052389ed3b723f2a796a5cc1c676fd36 Mon Sep 17 00:00:00 2001 From: Lucas Mundim Date: Tue, 5 Oct 2021 09:35:02 -0300 Subject: [PATCH 1/2] Rework only .doc file into .md. Solves #6095 --- src/Shared/Shared Code.doc | Bin 37376 -> 0 bytes src/Shared/SharedCode.md | 83 +++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) delete mode 100644 src/Shared/Shared Code.doc create mode 100644 src/Shared/SharedCode.md diff --git a/src/Shared/Shared Code.doc b/src/Shared/Shared Code.doc deleted file mode 100644 index 3bb7c7745d233990c715c0375c64f26e2e1af219..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 37376 zcmeI537AyXnfFgsFEmR@v-1&`3qb-(T4)79T$)wffB+_H7)?=C-BnUu)l^l}Aju3S zhB1zDP@_?knP^65bj&1ba3(HEj2he!nM{!QjE*qhm{B5u7}PiqpZ)#*=iXagU0v0* zIEE)l-F|*`?%B_I&wI98=T>ijVaTpK?jN(;6kTVUD)WA4e^XoF9^ihSZ?89I0rzry zzq7Mb&U1m=%Jl~%fj95^iCO)*{?*3(Zs?EIh{n*eTr~WxV~jbUtw$7A~8r~Dsd-od^J_h&IL8Nx>|<}_-3HU2-uoQ(Mf=4j0C@e#zlUzR?a zD#rw*9w*{;M;r5b>^q1*LJ1UIzB~fMiab24%B9OU{cygibPF#(J>T@}?T3;5-?8i= z-blcmwXB@Kb=CizTEruIaGRn`hGclvoCp+3gf5e%jqigWe@?U z?7HTiW0pOsfze*R-aUnKUV^J1&-c%l8@-!?qx4UgA8x=gu6-;*-%5Pn?)$sGAO6!% z*H6ipkMj8rj=r3I)6d_x`=%eioau)vHhq2c&2sU5_r0TBJ@oD6%;J1}yDw+oUe5H> z^~Z-obNoP)A6E+9700*x?eE)*O<&G^H8r^?{h%3?*D={ES49FJTmsAD;Y=**%uPpQ zp=Ir@v1r^mFPw_yR)sU6&;^M|CY?<;=kQN8C!(=bE)hQ<~AIlx8X=PppSXaHgAJW3TmXoT3C5teu-~bH>eHlTJkEv?r3$ zM5<*`IyE<(Oomq`V`{%~&YDCz8O|lrsgmVyoYIxuh)}*MLbH=eC+n&~gk+r7_H52c zCf3B9M9RsX0BrJ5t;g|msa#By0Dl5TBFBvH3SDwlR*Yhsyo zPB@#5wXRIAa}qfxk##b$=2#|{iV$e!x&~)qx{ISTRgAq zxpi%LNAPJ)v}D4$m=l)vW^EWRmjofG5xHhmy9Or|n!hHNauUr>t|RTZNl@!(qS+QB z=NC^A<6%T1d1R@$quM*+RMbnVyNA{B$<}S|`AfSBo{2@$Evdv6ZaQvuNMdDIx|6X) z!tGh>lF0b^BOcrPaw>=lpD!W8pN$iO%eE&eZ>h$#B}e9Nj|sayCQXlNaF)jrH_e}J zPa<)um3G?NS0)pYE@2et2ASnmx?A(6VzDTta8ss6`BtS^ZkKXm4J{2$b2{TB(_v|^ z6U$_)8bxE1T{VryniDD7!HFcvlGaa3 zy=Hqll`pHW$zE0RnmgI)NaV-`4e+It&C!D*h%+3OgeYI@N)#}ShM-`MpX3GM6s6Ai zIp(YBm0KC9j(Is))n476&|r&vq9~hG+HY)|6+K{8D&3KFI(*e`4W|;#F}kClzN>Z< z!wst%!VO5WB|(*~<0KU^K_~NrX6a51&a#4zt-gW&rX079$Z8#-z5ZsE)i3T11<5ox z=TLXlzNb`Op;HZYO1CMZlf8~ileoS8leq*v#WptTgT9qbi2fX=^QIE5?XBJ@luoZ= zC|af7kjS1E3bkh?)n)6lxmat1-xk?f#qQ0?SVU?xD-_DNb(vu-v_9l;6}P`zwH{Tr zVci&|V&%2QFPg6=U5#=^C>84{R-=ibai^DV>odnqrhmIbWW(99-2An%NP7+;_>L1N zO`2s(^@Y$ELZL;Am(M@VwpPAvVr$#z&WW6KIheHxX6=8<5eKH&Jhag|tS>M4((9n3uxnR2F_m-?#c!+Bb9hK*=)xX1?%db4fG3lIP%6fnnKMXA+|EKC)$!oJl&=lK%G62$)7M0LzyXH0TI2Xb=PBz`?f$`t?MqG{2{I@ZFj(_ z%o9D=1bv$)>_qW_CN5V~x?11^PG8ccVrA=FQB_Jir7cf8*+eUISo1ooZqDNSKN>h^ zbaf;x8J5|sCMwS4&|GGc_Dt-YRCBsvZaZU5DtF;Io+As1ynq^CBJZuu1RDyeQLO8u@iG!-xq|t94e}t=BG8g7rZsR&S_>!w)O7o^8u@h{*sP0K-gDScYw9ZuU#hlP`gG*Ymen`)K|9W z>lkgTdVa3(@Xq^@|`AxiCvC&elU|G3* z@JCsd7>6SPzULcM$5U)L22O!#FdZ&{MX(r_z$!>WE2N+U*1|ft0d9n^!A)>8d>w9q zTj4f%5dInd1rGk|;O`|}g{C?MZE?PJHtlr*w8ItxXBkJ^RdD@OgXpS6!?vIOH~}AsO*E?P$T2tJ+aQ< zSL@!Hp(Ct|o8z>)E2r08X`B)9=dL)}li1vIhnvOcR+&%1r4Yt$h%IRzqwjf3wZGbJ zFPz$+Z#Usxcn_)u@V!5r4J*L#4M+fQ1Em1YD=|^jf4}`}DTB2%7*T>#jpI~@=(Dexg%!KHmfC((wLW`QtL4g2i z*pQ?A@A=;^ta0W3PeKC0Kp>#8_y@2Ro`-Gl-|#xT0ej$A@Fr+H_%-Z<0gMF$VGx91 zB#eU5Fcli%WH<$;!F14AG6QD9a<~va4WEG)h(iLt2zy`s`A>ho`KLes>E3(yzIyMg z*IWCByuI1li(1JYssEF+6MY}4-8rMhjZwoZI@+?sn)q<5`xYxiev*-O>#IJLq3uo*6A{%(bD!Q-GgeHZ)}?18tSo_T$! zH^-mm>1deg$rWZ@|OwBiI4Igc=s}bubzn7zYz!3Y-N^a5gM~rLYT5WbJS|oB^MP zi=hp2aPYvvHxIsk@b&-u`oF`@f7|)O&gXVMvGalFc0O?Db332A5fg{2HtgK6QwOL@ zUg$$Z^nR;VT|^`4Czv;Evs05qfq~(%odO(InUJ z!uQ}Q*af>G$Z@@Dm;%!w3s=LPum!flHh2Mk$mypa!3*#ooD_Q%GORPR@IQquP~P%( zVX%+T@_J!DI??GX;Kh6dZpvH!wQs@7C*Z}m>%guR-W$hVY!8|ZzUuaxAy;h= zUW)lS%$8`E&-S3}vpwkgSXH+x$F4gyzZtFm^kq=n51}1LK?c;;SHM@`4p5sv4{Gn1 z;6Gt69Dx6U;k5h5VIrIakAklc1JQ+gm<#7Y3f9B5@YnDP_&T$T`&v#e?tk;8XI^^f zrF(9^=cR{kxbB+k)?e3=?YQQK^s1Is5&M^pTozG(s2#e(_KP1JkGQbEH{xMy)(-qT zYg)nK{*?#;Ft59U^K|s~3H`oL|Iuebk97Mop;oMX)`ph9Vp-81Kf;=>ZO#dy!i|+S zRc-MNl;JqvKiJb>J5~JE2;^GU-z!yVe@dbFhe(Ao+oqwjfgi(D@G=~L>S4_7a5S6 z;8U;~G;Vwo{t0%%Oh&$gd*66%_iMX7DXWTCE*B2(8ajq2;d7N=>Hi3;8@`D;4X{Kfm2f()j$MC+B^b zb;!CuoB)&IBDfU30r$aH_%-Z<#*xh1&;hr?x8M%=Hhh)Snb*Oi@JBG@f9N@*ybQYe z{H(j)dN%f38qeLad}#87GULBhPu5$53EO@Aw?20K@4B-?+GzEyCb$jM#@~kf;Tcd{ zJGA8|U@EA+XTn0b46={|wg2tlxBcI7|1>-U+u&9BCAq5!Tr9Mx4yjfA+Y8>y1VNR{%(Nl^m)x)*W9u3uF_rKije*9|C1#@f=aaA> z29IW*hDK7>94fntncp9F8zv7howeSesGRA#Zq?;!1E!5;)g_dr?%3HcE#c+ zKeK1udk=3La_tw*KbrII87MtrG&4NMF_)R;CT${Sx|wEXno~@pnabaEeE#&ZKK01e z`Uqw{wGgt=*y{qfacd3{a34D|iXyUQ+Z#sjf$^M3pn^Ub>#G|8(X*FS! z#7U2pMw_|kjy9Jq3{;0PTNn1P&O#0@F@dH4VJ@*L*wYQBzgcKv#EzPTNtqVo@aRcD za1}7M;{(I)+;4{8dAezuV2MCvEo)T_Fu9vtJQKBi~Nd~s56%`>x`-s-%A=W!g?^{$cFVy2lov?GHYHCV!Z z23qWAn~CGL06C@b)wPtm{ zFTf8G+>hV|_z%uez6u!%orM=+C+q{At?Lgbz+|`xE`@KveXtdN4f~*xb3SK72iywZ zf;-^b@Kw(7TnCTBldvBKbB?DT8lef+!)?E_Qz z(6zxs_gs>-ePSeYgNN?9J}SS#y_Dtm?N_eu6RCeyFXb#3uQ!=}6lwOB-$&v1$54ll zLN1jw?T}GChV<)AE)`uWDYK7k+&!EztGD*6_*L5P_qAsDL(tuiVm#BkfqFko?+EEV z5uFv+d10Ly)VU$|_klUJgev09YTW&$T8{VGU%<7y8`97_20CY|vu29JveIBRSPjR6 zNYr&_32E2h7ho=eR#*!+!cCxKLhASb0?)(ium^qxdqMl1QP2pdz%Dx zq&5y@kVp0=bL?+a^T!^0jL%N9VZ#RVt~RNIO>qAWIMtiF{ls-6RZDzT`?WgcfzAGj z*1i9JB~W|?%>WyZ9gns?HvAmSp`LpHcYfd5EHeZ5AIt5JDOtUFPUSP5eAe*>DlKo$ zs^ZmA%pv;~L3f>VkWqkC7uQq1dkZI$kjgmGW+H~krIVE29 zW)gr2V)-nbhD9$qK3ou1N+#u!Qc0PlL{c6pjg&=7BIOvurfd{w<0f8$exx-FhQmql zDAXc0QRkr-CF{ZQsHHOvgyTGBVK%{RcmytB&%Fp9fCpgxn(^ zHtay>UW7M1_F#&Apv~MM)I?kYpM{)9JEph-w88tjhcEg+w8%)%miuPVmit-I4+b9# zOW-1S5FP@Uey`bXdThyT#y$o7SD{Sfu$Iu{KWt~NlCa zB#!wXWf;%B-W$=wIK6qOx2E(4l}?kUCrvdvb!y)vT+(FpzTxe)^UTpR78<>`q6cw0 z+N`%xbjDprnRV7xZ!+o(tR9}~JbmY=ZyLR&rT1m@o{QeU)VoSLv91%fdIwAIsOaq$ zy~C?FB0HO^HU#o@SU9PLpE7Xm6xh1U4ANWdrI~z*X0;|wT8!XS_d@$DF~t+p4({Zt ziu;!vN})A(>22CR1wVO$&3#~Pbx>E? z+-LLTG(k>DQaEdxjnl8He=t}RtS%d8E_t-uczW*Ymzp=VP>`v0SC2OPbp}||B5#RD zuBhF#e&Yh&A8Ur;wgta`V*m^AWLzp$RX-N9yQ^Gujjb{z7cH)D<+FDQ)b+c)X0zFB zuDo(653cK3MMsICwe%)5UVNB~X7sMQ#xD&~JJs1`lE~JYwJ?`%uOlLgH{m&0P zWB-eCxZlk%F%~C8fAfnz5Ur1+y&3vV)Hr-|kj9L8F$Uw?Zu?f$e*bZv?NKqlg;-_d z9Lm2(#(%O7?=#LZ0QIOp-P!E=^0(f4Z*jc--s|hkiJ$oXOH**W3J>k~hfBokKZD164nfqg+bNPvA>!$MPlE2~>{lk* zEUB86sYXxPHLl96TonmaBv6q+MFJHGR3uQ5Kt%!-2~;Fdkw8TP6$u=U1j_CIwXY8D zcz(w>8$MQlBR}MP;^gp**D?OEfXy?Pty8NepcGXOm!&~t;^LErn{ z4ScI*?t^;JGXw4E9|L`V{50qpz;;mDuS4Npzxy70ZaUMJ=6`uCwYrzAO1*0D zzZa``r<1ZwefNI2=}qM&eqC;Q$5~U)XbwL;NytyH-lkLcq0&3GAiW_rJ<0s=%QxMo zSNW(&pdx{a1S%4!NT4EtiUcYWs7Rn9fr$MNl{#oD6 zYpq&^=6myo8Qs-hO@D6@Z9EcUMB~KdkrwbeEup&U((S#zgBrMrWU*z-IutRJOY4YFXc0=_3IfnctarN82=C2eRyvG_f-bpH* zNmSdPgBCQ~GRY;!2|~SDUjCYR81g?^$!YN5s_9X4_heUJ%QJ)gHEyZyx@@9{_?RVs zFaLl&S=P$)%Eg?py!;R`dwLJ$>7ARi``I%@X_wWdoe#_PaPs#vlJ5Q~jB|xDs@!); zAVBNufBMO#c%QJr J%>Nw;{D0vdC-(pV diff --git a/src/Shared/SharedCode.md b/src/Shared/SharedCode.md new file mode 100644 index 00000000000..2d01bc67401 --- /dev/null +++ b/src/Shared/SharedCode.md @@ -0,0 +1,83 @@ +# Shared Code + +## **Namespace** +All sahred code _must_ live in `Microsoft.Build.Shared` namespace. +___ + +## **Internal Access Only** +Shared code gets compiled into every assembly as it is referenced by. However this does _not_ mean that the shared types can migrate across the assemblies they are in. + +Even if two types in different assemblies have the same name and are in the same namespace, the CLR does _not_ recognize the types to be the same, because their assembly identities are different. + +As a result all shared code _must_ have **internal** access only. There should be _no_ public types in shared code. +___ + +## **Resources** +Shared code needs access to assembly resources e.g. for loading error messages for exceptions. Each assembly that shares code, _must_ define a class called `AssemblyResources` in the shared namespace, with an `internal static readonly` member of type `ResourceManager` called `resources`. Each sharing assembly is required to do this because only it knows what the manifest resource name (a.k.a. logical name) of its resources is. Shared code can then statically reference the assembly’s resources. If the `AssemblyResources` class is not defined, it is a compile-time error. + +The `AssemblyResources` class at a minimum must look like this: + +```cs +using System.Resources; +using System.Reflection; + +namespace Microsoft.Build.Shared +{ + internal static class AssemblyResources + { + internal static readonly ResourceManager resources = + new ResourceManager( + "", + Assembly.GetExecutingAssembly()); + } +} +``` + +NOTE: the class is explicitly marked `static`, because it only contains static members and methods -- making the class static prevents it from being instantiated, and allows the compiler to flag the (accidental) addition of instance members. +___ + +## **Shared Resources** +Shared code sometimes needs to define its own resources. If this were not allowed, then each sharing assembly would have to redefine the same set of resources on behalf of the shared code. As with code, maintaining multiple copies of the same resources is not desirable. + +Shared resources must be placed in the file `Strings.shared.resx` in the shared code directory. All resource names must be prefixed with “`Shared.`” to distinguish the shared resources from an assembly’s primary resources. Each sharing assembly must add an `internal static readonly` member of type `ResourceManager`, called `sharedResources`, to the `AssemblyResources` class. This is necessary because only the sharing assembly can assign the correct manifest resource name to the shared resources. Shared code can then statically reference the shared resources. The absence of either the `AssemblyResources` class, or the `sharedResources` member is a compile-time error. + +For assemblies that share resources, the `AssemblyResources` class at a minimum must look like this: + +```cs +using System.Resources; +using System.Reflection; + +namespace Microsoft.Build.Shared +{ + internal static class AssemblyResources + { + internal static readonly ResourceManager resources = + new ResourceManager( + "", + Assembly.GetExecutingAssembly()); + + internal static readonly ResourceManager sharedResources = + new ResourceManager( + "", + Assembly.GetExecutingAssembly()); + } +} +``` + +To simplify the retrieval of resources, the `AssemblyResources` class can optionally define a method called `GetString()` that searches both the assembly’s primary resources as well as its shared resources for a given string. For example: + +```cs +internal static string GetString(string name) +{ + string resource = resources.GetString(name, CultureInfo.CurrentUICulture); + + if (resource == null) + { + resource = sharedResources.GetString(name, CultureInfo.CurrentUICulture); + } + + return resource; +} +``` + +NOTE: if the above method is added to the `AssemblyResources` class, it is advisable to make both `resources` and `sharedResources` private (instead of `internal`) to unify access to assembly resources. \ No newline at end of file From e27cdc7c23e7da41f4c89dec7d83ab5d81dbac59 Mon Sep 17 00:00:00 2001 From: Lucas Fonseca Mundim Date: Tue, 5 Oct 2021 10:53:55 -0300 Subject: [PATCH 2/2] Update src/Shared/SharedCode.md Fix typo Co-authored-by: Rainer Sigwald --- src/Shared/SharedCode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Shared/SharedCode.md b/src/Shared/SharedCode.md index 2d01bc67401..955f9af23f8 100644 --- a/src/Shared/SharedCode.md +++ b/src/Shared/SharedCode.md @@ -1,7 +1,7 @@ # Shared Code ## **Namespace** -All sahred code _must_ live in `Microsoft.Build.Shared` namespace. +All shared code _must_ live in `Microsoft.Build.Shared` namespace. ___ ## **Internal Access Only**