《NET Framework Design Guidelines.doc》由会员分享，可在线阅读，更多相关《NET Framework Design Guidelines.doc（233页珍藏版）》请在三一办公上搜索。
1、.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 this document is to encourage consistency and predictabi
2、lity in the publicly exposed APIs while enabling integration with multiple languages and application models.Document InfoOwnerKCwalinaLast Saved1/1/0001Filedesignguidelines.docPrimary Reviewersurtlib;External reviewersnetprof; lapileadUEGlennHaContributorsThe following people substantially contribut
3、ed 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-Taleb, Steve Starck.Table of Contents 1Introduction71.1 Goals81.2 How
4、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 added133Naming Guidelines133.1 Capitalization Conventions143.1.1 Capitali
5、zation 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 Avoiding Language-specific Names223.3 Names of Assemblies and DLLs24
6、3.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 Parameters353.5.2 Names of Common Types363.5.3 Naming Enumerations383.6 Name
7、s 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 Class and Struct484.3 Choosing Between Class and Interface494.3.1 Abs
8、tract 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. Methods705.1.3 Read-Only and Write-Only Properties725.1.4 Indexed Proper
9、ty (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 Constructor Design855.1.13 Type Constructor Guidelines895.1.14 Fie
10、ld 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 Collections1036.1.1 Naming1036.1.2 Implementation1036.1.3 Collection Usage1046.
11、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 IDisposable Pattern1106.2.1 General1116.2.2 SafeHandle1126.2.3 Finalize1136
12、.2.4 Dispose1166.2.5 Other Instance Methods1176.2.6 Dispose Pattern1176.2.6.1Simple Pattern1186.2.6.2Complex Pattern1196.2.7 Example1206.2.7.1Simple Pattern Example1206.2.7.2Complex Pattern Example1226.2.8 Recreatable1256.3 IComparable1266.4 ICloneable1266.5 Delegates1276.6 Attributes1276.7 Exceptio
13、n1296.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 Design1377.1.3 Summary of Asynchronous Pattern1407.2 Optional Features141
14、7.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 Factories1487.12 Timeouts1517.13 Default Instance (Empty) Pattern
15、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 Guidelines1648.3.1 Throwing Exceptions1648.3.2 Exception Error Messages1688.
16、3.3 Handling Exceptions1698.4 Standard Exception Types172ArgumentException Usage1748.5 Wrapping Exceptions1759Usability1759.1 Problem Definition1759.2 Core Principles of Progressive API Design1789.2.1 Principle of Scenario-Driven Design1789.2.2 Principle of Customizable Defaults1809.2.3 Principle of
17、 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 Guidelines1909.3.4 Aggregate Component Guidelines19110Evolving Managed AP
18、Is19210.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 Patterns20611.3 Naming Guidelines20911.4 Usage Guidelines20911.4.1 Gener
19、al Usage20911.4.2 Generic Collections21011.4.3 Nullable21211.4.4 EventHandler21311.4.5 Comparer21311.5 Simulating Covariance21312Usage Guidelines21412.1 System.URI Usage21412.1.1 System.Uri Implementation Rules21412.1.2 FxCop Rules21512.2 Resources21512.3 OptionalValue Usage21712.4 System.Xml Usage2
20、1813Security21913.1 Protecting objects with permissions21913.2 Fully-trust class library code21913.3 Precautions for highly trusted code22013.4 Performance22013.5 General Code Access Security Guidelines22113.6 Security Related Coding Conventions22213.7 Specific Security Issues22513.7.1 Culture Aware
21、 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 Unmanaged Code23114.1.2 Using Unmanaged Code from Managed Code23314.1.3 Using COM from Managed C+23414.1.4 Using
22、 ReleaseComObject23414.2 Platform Support23514.3 Threading23615Appendixes23915.1 Appendix I: The .NET Framework Overview23915.1.1 Generics Overview23915.2 Appendix II: FxCop23915.3 Appendix III: C# Style Guide23915.3.1 Exposing Platform Specific23915.3.2 Synchronization and Concurrency24015.3.3 Remo
23、ting24015.3.4 Internationalization24015.3.5 Deployment24015.3.6 Component Model24015.3.7 Callback mechanisms24015.3.8 Remoting vs. Messages2401 Introduction Page: 7This section needs to be reworked. It needs to stress the importance of consistency, higher-level APIs, wide range of developers as the
24、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 problem is exacerbated by the fact that for years most of your functionality has been exposed in an unmanag
25、ed way. There is considerable code, design experience, and most importantly, faithful customers hard learned knowledge invested in the legacy design. Which parts of your libraries should be managed? How do these managed libraries interoperate with COM and other unmanaged applications? How does this
26、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 way to help class library designers more fully understand the trade-offs between different solutions. Rules
27、 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 violate these guidelines and for these violations to be rare and not far from the spirit of this document.
28、A well-designed managed class library has the following characteristics. It is consistent: Similar design patterns are implemented across libraries. It is predictable: Functionality is easily discoverable. There is typically only one way to perform a specified task. It is Web centric: It is designed
29、 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 is accessible to many different programming languages.1.1 GoalsMoving to a managed execution environment offers an opportunity to improve
30、 the programming model. For several reasons, we strongly advise designers to treat these guidelines as if they were prescriptive.We believe that developer productivity can be seriously hampered by inconsistent design.Development tools and add-ins will turn some of these guidelines into de facto pres
31、criptive rules, and reduce the value of non-conforming components. These non-conforming components will function, but not to their full potential.It is very important that you follow the guidelines provided here. However, there are instances where good library design dictates that these guidelines b
32、e broken. In such cases, it is important to provide solid justification.Relationship Page: 8We should probably move the section or rework it.to the Common Language SpecificationTargeting the common language specification (CLS) is an excellent way to ensure cross language interoperation. The CLS defi
33、nes a set of programmatically verifiable rules that governs the interoperation of types authored in different programming languages. Although the CLS encourages good library design, it does not enforce it. The CLS is a set of rules to be used by managed class library designers to guarantee that thei
34、r 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 library.Does the feature facilitate the type of API development we want to encourage in the managed space?Although we want the CLS t
35、o 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 confusing and bad design/usage discussions. For example, providing both safe and unsafe constructs forces users to decide which one
36、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 require some modification in order to target the runtime and our common type system. However, in order to be CLS compliant, we do not h
37、ave 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 included, because it is burdensome for a compiler to expose this feature.For more information, see the Common Type System specif
38、ication.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 expressiveness APIs and the high level ease of use APIs. However there are a few guidelines that must be read differently depending on which dev
39、elopers 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 developers. Examples:Typical guideline, applies regardless target developer: Do use PascalCasing for all public identifiers consisting of
40、 compound words. For example, use TextColor rather than Textcolor or Text_color.Specific guideline when targeting the high level developer: Consider static members for shared resource creation and instance members to manipulate proxies to such shared resources.Needs to get added to the mainline docT
41、radeoff: For targeting the higher level developers considers limiting the scenarios where static and instance members are used on the same type. Usability 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
42、 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. Specific guideline when targeting the low level developer: Do prefer collections over arrays. Collections are more usable and institutive in many cases.
43、 Collections provide more control over the contents of the container and are more versionable. For read-only values use of arrays often requires cloning and it is therefore more efficient to use collections in many read-only scenarios. Tradeoff: For targeting lower level developers it is often bette
44、r 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 can be inlined by the JIT. However usability studies have shown that some customers (Mort) have problems dealing with arrays. The problem lays in the conce
45、ptual overhead of understanding the techniques to declare arrays in VB. Collections provide them a simple and consistent model. Array usage for read 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
46、 about what the green and red dots meanFxCop is a code analysis tool that checks CLR assemblies for conformance to some of the guidelines described 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 Partially covered by FxCop rules. Do Do not Not covered by FxCop rules.
