NET Framework Design Guidelines

1、.net framework design guidelines microsoft confidential.net framework design guidelinesdesiging class libraries for the .net frameworkpublic version of the document can be found at overviewmoving to a managed execution environment offers an opportunity to improve the programming model. the goal of t

2、his document is to encourage consistency and predictability in the publicly exposed apis while enabling integration with multiple languages and application models.document infoownerkcwalinalast saved7/11/200512/15/2004filedesignguidelines.docprimary reviewersurtlib;external reviewersnetprof; lapilea

3、dueglennhacontributorsthe following people substantially contributed to the document: brad abrams, chris anderson, erik christensen, jason clark, krzysztof cwalina, patrick dussud, anders hejlsberg, jim miller, michael murray, lance olson, chi-yan tong, eric gunnerson, dare obasanjo, ahmed abou-tale

4、b, steve starck.table of contents 1introduction71.1 goals81.2 how to read the document91.2.1 document styles91.2.2 fxcop rules coverage102library design fundamentals102.1 targeting the breadth of developers102.1.1 architecture112.2 exposing functionality to com to be removed when new section added13

5、3naming guidelines133.1 capitalization conventions143.1.1 capitalization rules for identifiers143.1.2 capitalizing acronyms163.1.3 capitalizing compound words and common terms183.1.4 case sensitivity193.2 general naming conventions203.2.1 word choice203.2.2 using abbreviations and acronyms223.2.3 av

6、oiding language-specific names223.3 names of assemblies and dlls243.4 names of namespaces253.4.1 standard sub-namespace names263.4.2 namespaces and type name conflicts283.4.3 winfx namespace plan (ms internal)293.5 names of classes, value types, and interfaces333.5.1 names of generic type parameters

7、353.5.2 names of common types363.5.3 naming enumerations383.6 names of type members393.6.1 names of methods393.6.2 names of properties393.6.3 names of events413.6.4 naming fields433.7 naming parameters433.8 naming resources454type design guidelines464.1 types and namespaces474.2 choosing between cla

8、ss and struct484.3 choosing between class and interface494.3.1 abstract classes534.3.2 static classes544.4 interface design544.5 struct design564.6 enum design574.6.1 flags enum design614.6.2 adding values to enums634.7 nested types645member design655.1.1 property design655.1.2 properties vs. method

9、s705.1.3 read-only and write-only properties725.1.4 indexed property (indexer) design725.1.5 event design735.1.6 method design755.1.7 method overloading765.1.8 variable number of arguments785.1.9 operator overload design815.1.10 implementing equals and operator=835.1.11 conversion operators855.1.12

10、constructor design855.1.13 type constructor guidelines895.1.14 field design905.1.15 explicit member implementation935.2 parameter design955.2.1 argument checking955.2.2 parameter passing985.2.3 pointer arguments995.2.4 enums vs boolean arguments1006common contract implementations1036.1 collections10

11、36.1.1 naming1036.1.2 implementation1036.1.3 collection usage1046.1.4 generic collections usage1056.1.5 implementing ienumerable1066.1.6 arrays vs. collections1076.1.7 collection1076.1.8 indexed properties in collections1096.1.9 array valued properties1106.1.10 returning empty arrays1106.2 idisposab

12、le pattern1106.2.1 general1116.2.2 safehandle1126.2.3 finalize1136.2.4 dispose1166.2.5 other instance methods1176.2.6 dispose pattern1simple pattern1complex pattern1196.2.7 example1simple pattern example1complex pattern example1226.2.8 recreatable1256.3 icomparabl

13、e1266.4 icloneable1266.5 delegates1276.6 attributes1276.7 exception1296.8 equals1296.9 finalize1336.10 tostring1336.11 serializable draft1336.12 com visibility draft1357common design patterns1367.1 asynchronous pattern1367.1.1 introduction to asynchronous programming1367.1.2 asynchronous api design1

14、377.1.3 summary of asynchronous pattern1407.2 optional features1417.3 searcher1457.4 resource proxy1457.5 builder1457.6 cannonical type1457.7 static method holder1457.8 immutable types1457.9 static methods and singleton design1457.9.1 singleton pattern1457.9.2 static classes1467.10 callbacks1477.11

15、factories1487.12 timeouts1517.13 default instance (empty) pattern draft1537.14 obscuring low level funcationality1548error reporting and handling1548.1 benefits of exception handling1548.2 working with exceptions1568.2.1 exception handling examples from the framework1618.3 exception usage guidelines

16、1648.3.1 throwing exceptions1648.3.2 exception error messages1688.3.3 handling exceptions1698.4 standard exception types172§argumentexception usage1748.5 wrapping exceptions1759usability1759.1 problem definition1759.2 core principles of progressive api design1789.2.1 principle of scenario-drive

17、n design1789.2.2 principle of customizable defaults1809.2.3 principle of the aggregate component1829.2.4 principle of self documenting object models1859.3 summary of usability guidelines1899.3.1 general usability guidelines1899.3.2 scenario development guidelines1899.3.3 usable object model design g

18、uidelines1909.3.4 aggregate component guidelines19110evolving managed apis19210.1.1 consider existing consumers19210.1.2 naming19311generics19511.1 generics related terminology19711.2 general generics usage guidelines19811.2.1 generics and usability19911.2.2 generics and performance20211.2.3 common

19、patterns20611.3 naming guidelines20911.4 usage guidelines20911.4.1 general usage20911.4.2 generic collections21011.4.3 nullable<t>21211.4.4 eventhandler<t>21311.4.5 comparer<t>21311.5 simulating covariance21312usage guidelines21412.1 system.uri usage21412.1.1 system.uri implementat

20、ion rules21412.1.2 fxcop rules21512.2 resources21512.3 optionalvalue<t> usage21712.4 system.xml usage21813security21913.1 protecting objects with permissions21913.2 fully-trust class library code21913.3 precautions for highly trusted code22013.4 performance22013.5 general code access security

21、guidelines22113.6 security related coding conventions22213.7 specific security issues22513.7.1 culture aware string concerns22513.7.2 restricting access (friends)22713.8 summary of security issues23014misc23114.1 interoperating between managed and unmanaged code23114.1.1 exposing managed api to unma

22、naged code23114.1.2 using unmanaged code from managed code23314.1.3 using com from managed c+23414.1.4 using releasecomobject23414.2 platform support23514.3 threading23615appendixes23915.1 appendix i: the .net framework overview23915.1.1 generics overview23915.2 appendix ii: fxcop23915.3 appendix ii

23、i: c# style guide23915.3.1 exposing platform specific23915.3.2 synchronization and concurrency24015.3.3 remoting24015.3.4 internationalization24015.3.5 deployment24015.3.6 component model24015.3.7 callback mechanisms24015.3.8 remoting vs. messages2401 introduction this section needs to be reworked.

24、it needs to stress the importance of consistency, higher-level apis, wide range of developers as the target, platform, etc. designing managed, object oriented software is difficult. designing code to work with other managed libraries outside of your direct control is even more difficult. this proble

25、m is exacerbated by the fact that for years most of your functionality has been exposed in an unmanaged way. there is considerable code, design experience, and most importantly, faithful customer's hard learned knowledge invested in the legacy design. which parts of your libraries should be mana

26、ged? how do these managed libraries interoperate with com and other unmanaged applications? how does this fit into the overall microsoft strategy? what will impress your customers about a managed design?this document does not address all of these issues. instead it defines a set of guidelines as a w

27、ay to help class library designers more fully understand the trade-offs between different solutions. rules are made to be broken, and we understand that there are situations where it is necessary to stray from these guidelines. however, our hope is to force designers to make an explicit decision to

28、violate these guidelines and for these violations to be rare and not far from the spirit of this document.a well-designed managed class library has the following characteristics.· it is consistent: similar design patterns are implemented across libraries.· it is predictable: functionality

29、is easily discoverable. there is typically only one way to perform a specified task.· it is web centric: it is designed with cross context, cross process and cross machine execution in mind.· it is flexible: it is callable from semi-trusted code.· it is multi-language: functionality i

30、s accessible to many different programming languages.1.1 goalsmoving to a managed execution environment offers an opportunity to improve the programming model. for several reasons, we strongly advise designers to treat these guidelines as if they were prescriptive.we believe that developer productiv

31、ity can be seriously hampered by inconsistent design.development tools and add-ins will turn some of these guidelines into de facto prescriptive rules, and reduce the value of non-conforming components. these non-conforming components will function, but not to their full potential.it is very importa

32、nt that you follow the guidelines provided here. however, there are instances where good library design dictates that these guidelines be broken. in such cases, it is important to provide solid justification.relationship we should probably move the section or rework it.to the common language specifi

33、cationtargeting the common language specification (cls) is an excellent way to ensure cross language interoperation. the cls defines a set of programmatically verifiable rules that governs the interoperation of types authored in different programming languages. although the cls encourages good libra

34、ry design, it does not enforce it. the cls is a set of rules to be used by managed class library designers to guarantee that their apis will be callable across a wide range of programming languages. you should follow two guiding principles when determining which features to include in your class lib

35、rary.does the feature facilitate the type of api development we want to encourage in the managed space?although we want the cls to be rich enough to provide the ability to write any managed library exclusively in the cls, more is not always better. providing ten ways to do the same task leads to con

36、fusing and bad design/usage discussions. for example, providing both safe and unsafe constructs forces users to decide which one they want to use. the cls encourages correct behavior by only offering type safe constructs.is it burdensome for a compiler to expose the feature?all languages will requir

37、e some modification in order to target the runtime and our common type system. however, in order to be cls compliant, we do not have to create a large amount of additional work. the goal is for the cls to be as small as possible and still meet the first goal. for example, parameterized types are not

38、 included, because it is burdensome for a compiler to expose this feature.for more information, see the common type system < specification.1.2 how to read the document1.2.1 document stylesthe vast majority of the guidelines in this document apply equally well to the low level power and expressive

39、ness apis and the high level ease of use apis. however there are a few guidelines that must be read differently depending on which developers you are primarily targeting. the guidelines found in this document are annotated to make it clear where tradeoffs are required for the different levels of dev

40、elopers. examples:typical guideline, applies regardless target developer:· do use pascalcasing for all public identifiers consisting of compound words. for example, use textcolor rather than textcolor or text_color.specific guideline when targeting the high level developer: · consider stat

41、ic members for shared resource creation and instance members to manipulate proxies to such shared resources.needs to get added to the mainline doctradeoff: for targeting the higher level developers considers limiting the scenarios where static and instance members are used on the same type. usabilit

42、y studies have shown that static and instance members on the same type confuse some customers (mort). if it is critical for your api to be tailored for mort, you may consider not using static and instance members on the same type. be aware that tools will be able to mitigate the problem a bit. speci

43、fic guideline when targeting the low level developer: · do prefer collections over arrays. collections are more usable and institutive in many cases. collections provide more control over the contents of the container and are more versionable. for read-only values use of arrays often requires c

44、loning and it is therefore more efficient to use collections in many read-only scenarios. tradeoff: for targeting lower level developers it is often better to use arrays for read-write scenarios. arrays have a lower memory footprint which helps reduce working set and access to elements in an array c

45、an be inlined by the jit. however usability studies have shown that some customers (mort) have problems dealing with arrays. the problem lays in the conceptual overhead of understanding the techniques to declare arrays in vb. collections provide them a simple and consistent model. array usage for re

46、ad only scenarios is discouraged even in low level apis as the cost of cloning the array is prohibitive.1.2.2 fxcop rules coveragesomewhere we should talk about what the green and red dots meanfxcop is a code analysis tool that checks clr assemblies for conformance to some of the guidelines describe

47、d in this document. the tool checks assemblies against a set of rules that cover the guidelines, and displays violations to these rules. each guideline in this document is annotated by the coverage that fxcop gives, and the rules that cover it:fully covered by fxcop rules:· do · do not par

48、tially covered by fxcop rules.· do · do not not covered by fxcop rules.· do · do not 2 library design fundamentals2.1 targeting the breadth of developersthis document describes how to design apis that are both powerful and usable for the breadth of developers. this design paradig

49、m delivers on one of the core value propositions of the framework; which is to offer a unified programming model regardless of programming language choice. by following these guidelines you can create a framework that offers a single, consistently available, set of functionality that is applicable r

50、egardless of the application type (client, server, or service) or programming language. it is true that all developers are not solving the same kind of problems. different types of developers require different levels abstraction and different amounts of control and power. these different types of de

51、velopers want different things out of the libraries they use. one class of developers, who typically use c+ or c# value power and expressiveness in apis they use. we refer to these power apis as low level apis because they offer a low level of abstraction. on the other hand, some developers that typ

52、ically use c# or vb.net value productivity and simplicity. we refer to these more abstract apis as high level because they offer a higher level of abstraction. by using a layered api design it is possible to build a single api set that meets these diverse needs2.1.1 architecture the general guidelin

53、e for accomplishing the goal of building a single api set that targets the breadth of developers is to factor your api set into low-level classes that expose all the power and expressiveness and a higher level library that wraps the low level classes with convenience functionality. figure 1 is a sim

54、ple illustration of this concept. low level power and expressivenesstarget: einstein and elvis high level simplicity and ease of usetarget: mort and elvis figure 1: factoring of functionality between high level and low level developers. an application of this pattern is the apis exposed in asp.net (

55、in the system.web namespace). for the power an expressiveness crowd asp.net offers a low level http runtime layer that allows developers to code against the raw requests coming into the web server with very little abstraction provided. however asp.net also offers a rich set of web controls such as a

56、 listbox or calendar control that allows developers to code against properties and methods on a class without worrying about the requestresponse patterns needed to implement the behavior. in this way asp.net offers a single api set that is consistently available but has layers that target different

57、developer audiences. notice it is totally possible that based on customer scenarios one layer or another may not be needed. that is some functionality may only expose a low level api. also note that care should be taken when implementing high level classes in terms of the lower level classes, the high level d