Symbols

{ } (braces), C# style conventions, 466–469

, (comma), C# style conventions, 475–476

- (hyphens), naming conventions, 53

(/* . */), multiline syntax, comments, 482

(// .), single line syntax, comments, 482

[TypeForwardedTo], moving types, 532–533

_ (underscore), naming conventions, 53, 481–482

A

abbreviations, naming conventions, 55–56

abstract classes, type design guidelines, 98–102

abstract members

adding, 539

changing

to virtual members, 553

virtual members to, 553

override members, removing an override of an abstract member, 543–544

abstractions

designing frameworks, 34–36

extensibility, 239–241

self-documenting object models, principle of, 34–36

AccessViolationException, 276

acronyms

capitalization, 45–48

naming conventions, 55–56

adding

abstract members, 539

base interfaces to interfaces, 536

members

to interfaces, 541

to unsealed types, 539–540

method parameters, 546

readonly modifier to structs, 535, 550

reference type fields to structs, 540

second declaration to generic interfaces, 536–537

static modifiers, 549

aggregate components

component-oriented design, 331–334

design patterns, 329–338

designing, 335–338

factored types, 334–335

alphanumeric characters, naming conventions, 53

API (Application Programming Interface)

availability, 13–14

consistency, 34

designing frameworks

low barrier to entry, principle of, 23–29

scenario-driven framework design, 16–23

self-documenting object models, principle of, 29–36

exceptions and API consistency, 250

heavy API design processes, 2

intuitive API, 33–34

layered architecture, principle of, 36–39

naming new versions of existing API, 58–61

sample specification, 523–528

Stopwatch specification, 524–528

strong typing, 33–34

unification, 13–14

well-designed frameworks, qualities of, 3

backward compatibility, 2

borrowing from existing proven designs, 6–7

consistency, 7–8

evolution, 7

expense, 4–5

integration, 7

OO design, 2

prototyping, 2

simplicity, 3–4

trade-offs, 6

ApplicationException, 274

applications

models, namespaces, 65–66

RAD, progressive frameworks, 13

architectures (layered), principle of, 36–39

ArgumentException, 275–276

ArgumentNullException, 275–276

ArgumentOutOfRangeException, 275–276

arguments, validation, 207–210, 480

arrays

collections versus, 302–303

design patterns, 430–433

usage guidelines, 287–291

ASCII characters

code restrictions, 479

naming conventions, 54

Unicode escape sequences (uXXXX), 479

assemblies

naming conventions, 61–62

renaming, 530–531

types and assembly metadata, 127–129

assignment-expression-throw, C# style conventions, 480

Async Patterns, 502

Async method return types, 348–351

Async variants of existing synchronous methods, 353–354

await foreach, 363–365

cancellation, 512–513

choosing, 339–341, 503–504

Classic Async Patterns, 361, 503–509

consistency, 355–361

context, 357–358

deadlock, 358

design patterns, 339–365

Event-Based Async Patterns, 361–362, 510–512

exceptions to Async methods, 359–361

IAsyncDisposable interface, 362

IAsyncEnumerable<T> interface, 362–365

implementation guidelines, 355–361

incremental results, 516

Out parameters, 512

progress reporting, 513–516

Ref parameters, 512

Task-Based Aync Pattern, 341–347

Task.Status consistency, 355–357

ValueTask structs, 358–359

ValueTask<TResult> structs, 358–359

attached DP design, 369–370

attributes, usage guidelines, 291–294

auto-implemented properties, C# style conventions, 479

await foreach, Async Patterns, 363–365

await using, Dispose Patterns, 393–394

B

backward compatibility, well-designed frameworks, qualities of, 2

base classes

extensibility, 242–244

moving members to, 541

base interfaces

adding to interfaces, 536

moving members to, 541

base members, masking, 539

BCL type names, C# style conventions, 476

behaviors, changing, 553–555

Binary serialization, 493

boolean parameters, choosing, 205–207

borrowing from existing proven designs, well-designed frameworks, 6–7

braces ({ }), C# style conventions, 466–469

breaking changes, 529

assemblies, renaming, 530–531

behaviors, changing, 553–555

classes

changing structs to, 537–538

changing to structs, 537

moving members to base classes, 541

compilation breaks, 530

finalizers, removing from

sealed types, 542

unsealed types, 542

interfaces

adding a second declaration to interfaces, 536–537

adding base interfaces to interfaces, 536

adding members to, 541

moving members to base interfaces, 541

members

adding abstract members, 539

adding to interfaces, 541

adding to unsealed types, 539–540

changing member signatures, 545–553

masking base members, 539

moving to base classes, 541

moving to base interfaces, 541

moving to derived types, 542

overloading, 544–545

override members, 540

removing an override of a virtual member, 543

removing an override of an abstract member, 543–544

removing non-override members, 543

namespaces, adding namespaces that conflict with existing types, 531–532

private fields

removing from serializable types, 544

renaming on serializable types, 544

recompile breaks, 530

reflection breaks, 530

runtime breaks, 529

structs

adding first reference type field to, 540

adding readonly modifier to structs, 535–536

changing classes to, 537

changing to classes, 537–538

ref structs, 538

types

changing namespaces, 535

moving, 532–533

moving members to derived types, 542

names, case sensitivity, 534

removing, 533

removing finalizers from sealed types, 542

removing finalizers from unsealed types, 542

removing private fields on serializable types, 544

renaming private fields on serializable types, 544

sealing unsealed types, 534

unsealing sealed types, 534

brevity, naming conventions, 52

buffer operators

arrays, 430–433

data transformation operations, 445–451

design patterns, 430–445

fixed sizes, 451–452

OperationStatus value, 458–463

partial writes to buffers, 458–463

predetermined sizes, 451–452

Spans, 431–445

Try-Write Pattern, 452–458

C

C#

coding style conventions, 465–466

ASCII characters, code restrictions, 479

assignment-expression-throw, 480

auto-implemented properties, 479

BCL type names, 476

braces ({ }), 466–469

collection initializers, 478

commas ( , ), 475–476

comments, 482–483

expression-bodied members, 478–479

file organization, 483–485

if.throw, 480

indents, 465–466

language keywords, 476

member modifiers, 473–475

nameof (.) syntax, 479

naming conventions, 480–482

object initializers, 477–478

readonly modifiers, 479

spaces, 469–470

this.476

Unicode escape sequences (uXXXX), 479

var keyword, 476–477

vertical whitespace, 472–473

language-specific names, naming conventions, 57

C++, language-specific names, naming conventions, 57

callbacks, extensibility, 231–237

camelCasing, 43

C# style conventions, 481–482

naming conventions, 481–482

parameter names, 79

cancellation, Async Patterns, 512–513

capitalization, 42

acronyms, 45–48

case sensitivity, 51–52

compound words, 48–51

identifiers, 42–44

camelCasing, 43

PascalCasing, 42–44

case sensitivity

capitalization, 51–52

type names, 534

change notification events, DP, 371

changing

abstract members to virtual members, 553

behaviors, 553–555

classes to structs, 537

constant field values, 552

default values, in optional parameters, 552

member

signatures, 545–553

visibility, 548–549

method

parameters types, 546

return types, 547–548

non-virtual members to virtual members, 553

notification events in properties, 163–165

optional parameters to required, 551–552

property types, 548

reference parameters, 549–550

required parameters to optional, 551

runtime error exceptions to usage error exceptions, 553–554

structs to classes, 537–538

type names

case sensitivity, 534

changing namespaces, 535

usage error exceptions to functioning behavior, 554

values returned type, from a method, 554–555

virtual members to abstract members, 553

choosing

boolean parameters, 205–207

enum parameters, 205–207

exceptions for throwing, 260–264

member

methods, 152–158

properties, 152–158

classes

abstract classes, type design guidelines, 98–102

base classes

extensibility, 242–244

moving members to, 541

changing

classes to structs, 537

structs to classes, 537–538

defined, 84

members, moving to base classes, 541

naming conventions, 67–70

common types, 71

enumerations, 72–74

generic type parameters, 70–71

static classes

defined, 84

type design guidelines, 102–104

type design guidelines, 89–100, 102–104

unsealed classes, extensibility, 228–229

Classic Async Patterns, 361, 503–509

Close() method, Dispose Patterns, 382–383

CLR (Common Language Runtime), language-specific names and naming conventions, 57

collections

arrays versus, 302–303

custom collections, 302–303

initializers, C# style conventions, 478

live collections, 301–302

parameters, 296–297

properties, 298–302

return values, 298–302

snapshot collections, 301–302

usage guidelines, 294–296

arrays versus collections, 302–303

collection properties, 298–302

custom collections, 302–303

live collections, 301–302

parameters, 296–297

return values, 298–302

snapshot collections, 301–302

ComException, 278

commas ( , ), C# style conventions, 475–476

comments

C# style conventions, 482–483

“I” usage, 483

multiline syntax (/* . */), 482

passive voice, 483

personification, 483

single-line syntax (// .), 482

“we” usage, 483

common names, naming conventions, 57–58

compatibility (backward), well-designed frameworks, 2

compilation breaks, 530

component-oriented design, 331–334

compound words, capitalization, 48–51

ConfigureAwait modifier, await using, 393–394

consistency

Async Patterns, 355–361

self-documenting object models, principle of, 34

Task.Status, 355–357

well-designed frameworks, qualities of, 7–8

constant field values, changing, 552

constructors

designing, 165–172

type constructors, 172–175

contravariance, design patterns, 412–417

conversion operators, 198-C05.1827

core namespaces, 66

costs, well-designed frameworks, 4–5

covariance, design patterns, 412–415, 417–423

customizing

collections, 303–305

event handlers, obsolete guidance, 491–492

exceptions

designing, 279–280

obsolete guidance, 492–493

D

Data Contract serialization, 493, 495–499

data transformation operations, 445–451

DateTime struct, usage guidelines, 306–308

DateTimeOffset struct, usage guidelines, 306–308

deadlock, Async Patterns, 358

declarations, adding to interfaces, 536–537

default values, changing in optional parameters, 552

derived types, moving members to, 542

design patterns

aggregate components, 329–338

arrays, 430–433

Async Patterns, 339–365, 502

cancellation, 512–513

choosing between Async Patterns, 503–504

Classic Async Patterns, 503–509

Event-Based Async Patterns, 503–504, 510–512

incremental results, 516

Out parameters, 512

progress reporting, 513–516

Ref parameters, 512

buffer operators, 430–445

arrays, 430–433

fixed sizes, 451–452

OperationStatus value, 458–463

partial writes to buffers, 458–463

predetermined sizes, 451–452

Spans, 431–445

Try-Write Pattern, 452–458

contravariance, 412–417

covariance, 412–415, 417–423

Dispose Patterns, 372–394, 511–517

DP, 366–372

factories, 394–399

LINQ, 400–408

optional features, 408–411

Spans, 431–445

Template Method Pattern, 423–425

timeouts, 426–427

Try-Write Pattern, 452–458

XAML readable types, 427–430

.Design subnamespaces, 489

designing

aggregate components, 335–338

component-oriented design, 331–334

constructors, 165–175

custom exceptions, 279–280

error messages, 264–265

events, 175–180

extensibility, 227–228

abstractions, 239–241

base classes, 242–244

callbacks, 231–237

events, 231–237

limiting, 244–246

protected members, 230

sealing, 244–246

unsealed classes, 228–229

virtual members, 237–239

fields, 180–183

frameworks, 3, 9–11, 15–16

abstractions, 34–36

backward compatibility, 2

consistency, 7–8

evolution, 7

existing proven designs, borrowing from, 6–7

expense, 4–5

integration, 7

low barrier to entry, principle of, 23–29

multiframework platforms, 12–13

OO design, 2

programming languages, 11–12

progressive frameworks, 12–15

prototyping, 2

scenario-driven framework design, 16–23

self-documenting object models, principle of, 29–39

simplicity, 3–4

trade-offs, 6

members

boolean parameters, 205–207

choosing methods, 152–158

choosing properties, 152–158

conversion operators, 198-C05.1827

enum parameters, 205–207

explicit implementation of interface members, 148–152

extension methods, 184–192

fields, 180–183

inequality operators, 200–202

members with variable number of parameters, 214–218

operator overloads, 192–198

overloading members, 136–148

parameter argument validation, 207–210

parameter passing, 210–214

parameters, 202–204

pointer parameters, 218–219

tuples in member signatures, 220–226

parameters, 202–204

argument validation, 207–210

boolean parameters, 205–207

enum parameters, 205–207

members with variable number of parameters, 214–218

passing, 210–214

properties, 158–160

change notification events, 163–165

indexed properties, 161–163

types, 84–85

assembly metadata and types, 127–129

classes, 89–104

constructors, 172–175

enums, 111–124

interfaces, 92–100, 104–106

namespaces, 85–88

nested types, 124–127

strings, 129–133

structs, 89–92, 106–111

diacritical marks, naming conventions, 55

Dispose (bool) method, Dispose Patterns, 376–380

Dispose (true) method, Dispose Patterns, 377–378

Dispose Patterns

await using, 393–394

basic Dispose Patterns, 375–383

Close() method, 382–383

ConfigureAwait modifier, 393–394

design patterns, 372–394

Dispose (bool) method, 376–380

Dispose (true) method, 377–378

finalizable types, 383–387, 511–517

IAsyncDisposable interface, 391–392

IDisposable method, 382–383

rehydration, 381–382

scoped operations, 387–391

SuppressFinalize method, 378

DLL (Dyanmic-Link Libraries), naming conventions, 61–62

DP (Dependency Properties), 365–366

attached DP design, 369–370

change notification events, 371

design patterns, 366–372

validation, 370

value coercion, 371–372

E

enums

adding values to, 123–124

defined, 84

flag enums, type design guidelines, 119–123

naming conventions, 72–74

parameters, choosing, 205–207

type design guidelines, 111–118

equality operators

reference types, 328

usage guidelines, 324–328

value types, 327

error exceptions

runtime error exceptions, changing to usage error exceptions, 553–554

throwing new types of, 555

usage error exceptions, changing

to functioning behavior, 554

runtime error exceptions to, 553–554

error handling, exceptions and, 250–252

error messages, designing, 264–265

event handlers (custom), obsolete guidance, 491–492

Event-Based Async Patterns, 361–362, 503–504, 510–512

events

change notification events, DP, 371

custom event handlers, obsolete guidance, 491–492

designing, 175–180

extensibility, 231–237

naming conventions, 77–78

notification events, changing in properties, 163–165

evolution of well-designed frameworks, qualities of, 7

exceptions

AccessViolationException, 276

API consistency, 250

ApplicationException, 274

ArgumentException, 275–276

ArgumentNullException, 275–276

ArgumentOutOfRangeException, 275–276

Async methods, 359–361

ComException, 278

custom exceptions

designing, 279–280

obsolete guidance, 492–493

error exceptions, throwing new types of, 555

error handling, 250–252

error messages, 264–265

ExecutionEngineException, 278

FormatException, 278–279

handling, 249–254, 265–271

IndexOutOfRangeException, 276

instrumentation and, 254

InvalidOperationException, 274–275

NullReferenceException, 276

object-oriented languages, 249–250

OperationCanceledException, 278

OutOfMemoryException, 277–278

performance and, 281

Tester-Doer Pattern, 281–282

Try Pattern, 282–286

PlatformNotSupportedException, 279

runtime error exceptions, changing to usage error exceptions, 553–554

SEHException, 278

self-documenting object models, 33

StackOverflowException, 276–277

SystemException, 274

TaskCanceledException, 278

throwing, 254–260

choosing exceptions, 260–264

error messages, 264–265

from existing thrown types, 555

new types of error exceptions, 555

types, 273–279

unhandled exception handlers, 253

usage error exceptions

changing runtime error exceptions to, 553–554

changing to functioning behavior, 554

wrapping, 271–273

ExecutionEngineException, 278

existing proven designs (well-designed frameworks), qualities of, 6–7

expense, well-designed frameworks, 4–5

explicit implementation of interface members, 148–152

exposing layers

in the same namespace, 38–39

in separate namespaces, 38

expression-bodied members, C# style conventions, 478–479

expression-throw, C# style conventions, 480

extensibility, 227–228

abstractions, 239–241

base classes, 242–244

callbacks, 231–237

events, 231–237

limiting, 244–246

protected members, 230

sealing, 244–246

unsealed classes, 228–229

virtual members, 237–239

extension methods, 184–192

F

factored types, aggregate components, 334–335

factories, design patterns, 394–399

features (optional), design patterns, 408–411

fields

designing, 180–183

naming conventions, 78–79

private fields

removing from serializable types, 544

renaming private fields on serializable types, 544

file organization, C# style conventions, 483–485

finalizable types, Dispose Patterns, 383–387, 511–517

Finalize method, Dispose Patterns, 378

finalizers, removing

sealed types, 542

from unsealed types, 542

first reference type field, adding to structs, 540

fixed buffer sizes, 451–452

flag enums, type design guidelines, 119–123

FormatException, 278–279

Framework Design Guidelines, naming conventions, 480

frameworks

designing, 3, 9–11, 15–16

abstractions, 34–36

backward compatibility, 2

borrowing from existing proven designs, 6–7

consistency, 7–8

evolution, 7

expense, 4–5

integration, 7

low barrier to entry, principle of, 23–29

multiframework platforms, 12–13

naming conventions, 480

OO design, 2

programming languages, 11–12

progressive frameworks, 12–15

prototyping, 2

scenario-driven framework design, 16–23

self-documenting object models, principle of, 29–36

simplicity, 3–4

trade-offs, 6

development of, 1–3

multiframework platforms, 12–13

progressive frameworks, 12–15

usability studies, scenario-driven framework design, 21–23

well-designed frameworks, qualities of, 3

backward compatibility, 2

borrowing from existing proven designs, 6–7

consistency, 7–8

evolution, 7

expense, 4–5

integration, 7

OO design, 2

prototyping, 2

simplicity, 3–4

trade-offs, 6

G

generic interfaces, adding a second declaration to, 536–537

generic type parameters, naming conventions, 70–71

guidance (obsolete), 487–488

Async Patterns, 502

cancellation, 512–513

choosing between Async Patterns, 503–504

Classic Async Patterns, 503–509

Event-Based Async Patterns, 503–504, 510–512

incremental results, 516

Out parameters, 512

progress reporting, 513–516

Ref parameters, 512

custom event handlers, 491–492

custom exceptions, 492–493

Dispose Patterns, finalizable types, 511–517

namespaces, 489–490

.Interop subnamespaces, 490

.Permissions subnamespaces, 489–490

naming conventions, 488

serialization, 493

.NET serialization technologies, 493

usage guidelines, 493–502

H

heavy API design processes, 2

Hungarian notation

C# style conventions, 482

naming conventions, 53, 482

hyphens (-), naming conventions, 53

I

“I” in comments, 483

IAsyncDisposable interface

Async Patterns, 362

Dispose Patterns, 391–392

IAsyncEnumerable<T> interface, Async Patterns, 362–365

ICloneable struct, usage guidelines, 308–309

IComparable<T> struct, usage guidelines, 309–311

identifiers

capitalization, 42, 44

camelCasing, 43

PascalCasing, 42–44

naming conventions, 54

type parameters (generic), naming conventions, 70–71

IDisposable method, Dispose Patterns, 377, 382–383

IEnumerable<T> method, LINQ support, 402–403

if.throw, C# style conventions, 480

implementation

Async Patterns, 355–361

auto-implemented properties, 479

expression-bodied members, 478–479

interface members, explicit implementation of, 148–152

System.Uri, 322–323

incremental results, Async Patterns, 516

indents, C# style conventions, 471–472

indexed properties, designing, 161–163

IndexOutOfRangeException, 276

inequality operators, 200–202

infrastructure namespaces, 66

initializers, C# style conventions

collection initializers, 478

object initializers, 477–478

instrumentation, exceptions and, 254

integration (well-designed frameworks), qualities of, 7

interfaces

abstractions, extensibility, 239–241

adding, members, 541

base interfaces

adding to interfaces, 536

moving members to, 541

defined, 84

generic interfaces, adding a second declaration to, 536–537

members

adding, 541

adding to interfaces, 541

implementing explicitly, 148–152

moving to base interfaces, 541

naming conventions, 67–70

common types, 71

enumerations, 72–74

generic type parameters, 70–71

type design guidelines, 92–100, 104–106

.Interop subnamespaces, 490

intuitive API, 33–34

InvalidOperationException, 274–275

IQueryable<T> method, LINQ support, 403–404

J - K

keywords (language)

C# style conventions, 476

var, C# style conventions, 476–477

L

language keywords, C# style conventions, 476

languages (programming), framework design, 11–12

language-specific names, naming conventions, 56–58

layered architecture, principle of, 36–39

limiting, extensibility, 244–246

LINQ (Language-Integrated Queries)

design patterns, 400–408

overview of, 400–401

support

IEnumerable<T> method, 402–403

implementation, 402

IQueryable<T> method, 403–404

query patterns, 404–408

live collections, 301–302

low barrier to entry, principle of, 23–29

M

masking base members, 539

members

abstract members

adding, 539

changing to virtual members, 553

changing virtual members to, 553

removing an override of an abstract member, 543–544

base members, masking, 539

changing, member signatures, 545–553

constructors

designing, 165–172

type constructors, 172–175

designing

boolean parameters, 205–207

conversion operators, 198-C05.1827

enum parameters, 205–207

events, 175–180

extension methods, 184–192

fields, 180–183

inequality operators, 200–202

members with variable number of parameters, 214–218

operator overloads, 192–198

parameter argument validation, 207–210

parameter passing, 210–214

parameters, 202–204

pointer parameters, 218–219

tuples in member signatures, 220–226

events, designing, 175–180

expression-bodied members, 478–479

interface members, implementing explicitly, 148–152

masking base members, 539

methods, choosing, 152–158

modifiers, C# style conventions, 473–475

moving to

base classes, 541

base interfaces, 541

derived types, 542

non-override members, removing, 543

non-virtual members, changing to virtual members, 553

overloading, 136–148, 544–545

override members, 540

removing an override of a virtual member, 543

removing an override of an abstract member, 543–544

parameters, designing, 202–204

properties

change notification events, 163–165

choosing, 152–158

designing, 158–160

indexed properties, 161–163

protected members, extensibility, 230

signatures

changing, 545–553

tuples in, 220–226

unsealed types, adding members to, 539–540

virtual members

changing abstract members to, 553

changing to abstract members, 553

extensibility, 237–239

removing an override of a virtual member, 543

visibility, changing, 548–549

metadata, assembly metadata and types, 127–129

methods

Async methods

exceptions to, 359–361

return types, 348–351

Close() method, 382–383

Dispose (bool) method, 376–380

Dispose (true) method, 377–378

extension methods, 184–192

IDisposable method, Dispose Patterns, 377, 382–383

IEnumerable<T> method, LINQ support, 402–403

IQueryable<T> method, IQueryable<T> method, 403–404

member methods, choosing, 152–158

naming conventions, 74–75, 196–197

operators and method names, 196–197

parameters

adding, 546

changing types, 546

removing, 546

renaming, 545

reordering parameters by the same type, 547

reordering parameters of differing types, 547

return types, changing, 547–548

static TryParse methods, 286

struct methods

adding readonly modifiers, 550

removing readonly modifiers, 551

SuppressFinalize method, 378

synchronous methods, Async variants of, 353–354

Try methods, value-producing Try methods, 284–285

values returned type, changing from a method, 554–555

modifiers

member modifiers, C# style conventions, 473–475

readonly modifiers

adding to struct methods, 550

C# style conventions, 479

removing from struct methods, 551

static modifiers, adding/removing, 549

moving

members to

base classes, 541

base interfaces, 541

derived types, 542

types

via [TypeForwardedTo], 532–533

without [TypeForwardedTo], 533

multiframework platforms, 12–13

multiline syntax (/* . */), comments, 482

N

nameof (.) syntax, C# style conventions, 479

namespaces

adding namespaces that conflict with existing types, 531–532

application models, 65–66

core namespaces, 66

infrastructure namespaces, 66

naming conventions, 63–67

obsolete guidance, 489–490

subnamespaces

.Design subnamespaces, 489

.Interop subnamespaces, 490

.Permissions subnamespaces, 489–490

naming conventions, 489–490

technology namespace groups, 66–67

type design guidelines, 85–88

type names, changing, 535

type names, conflicts, 65

application models, 65–66

core namespaces, 66

infrastructure namespaces, 66

technology namespace groups, 66–67

naming conventions, 41–42

abbreviations, 55–56

acronyms, 55–56

alphanumeric characters, 53

API, naming new versions of existing API, 58–61

ASCII characters, 54

assemblies, 61–62

brevity, 52

C# style conventions, 480–482

camelCasing, 481, 482

capitalization, 42

acronyms, 45–48

case sensitivity, 51–52

compound words, 48–51

identifiers, 42–44

classes, 67–70

common types, 71

enumerations, 72–74

generic type parameters, 70–71

common names, 57–58

custom collections, 305

diacritical marks, 55

DLL, 61–62

enumerations, 72–74

events, 77–78

fields, 78–79

Framework Design Guidelines, 480

Hungarian notation, 53

hyphens (-), 53

identifiers, 54

capitalization, 42–44

type parameters (generic), 70–71

interfaces, 67–70

common types, 71

enumerations, 72–74

generic type parameters, 70–71

language-specific names, 56–58

methods, 74–75, 196–197

namespaces, 63–67

obsolete guidance, 488

operators, 196–197

overload operator parameters, 80

packages, 61–62

parameters, 79–80

PascalCasing, 480–481

properties, 75–76

readability, 52

resources, 81

self-documenting object models, 30–32

structs, 67–70

common types, 71

enumerations, 72–74

generic type parameters, 70–71

subnamespaces, 489–490

type members, 74

events, 77–78

fields, 78–79

methods, 74–75

properties, 75–76

types (common), 71

underscores (_), 53, 481–482

word choice, 52–55

nested types, design guidelines, 124–127

.NET serialization technologies, 493

non-override members, removing, 543

non-virtual members, changing to virtual members, 553

notification events, changing in properties, 163–165

Nullable<T> struct, usage guidelines, 311–312

NullReferenceException, 276

O

object initializers, C# style conventions, 477–478

object models (self-documenting), principle of, 29–30

abstractions, 34–36

consistency, 34

exceptions, 33

naming, 30–32

strong typing, 33–34

Object.Equals, usage guidelines, 312–314

reference types, 314

value types, 314

Object.GetHashCode, usage guidelines, 315–316

object-oriented design, 2

object-oriented languages, exceptions and, 249–250

Object-Oriented Programming, 2

objects, usage guidelines, 312

Object.Equals, 312–314

Object.GetHashCode, 315–316

Object.ToString, 316–318

obsolete guidance, 487–488

Async Patterns, 502

cancellation, 512–513

choosing between Async Patterns, 503–504

Classic Async Patterns, 503–509

Event-Based Async Patterns, 503–504, 510–512

incremental results, 516

Out parameters, 512

progress reporting, 513–516

Ref parameters, 512

custom event handlers, 491–492

custom exceptions, 492–493

Dispose Patterns, finalizable types, 511–517

namespaces, 489–490

.Design subnamespaces, 489

.Interop subnamespaces, 490

.Permissions subnamespaces, 489–490

naming conventions, 488

serialization, 493

usage guidelines, serialization, 493–502

OO (Object-Oriented) design, 2

OOP (Object-Oriented Programming), 2

OperationCanceledException, 278

operations (scoped), Dispose Patterns, 387–391

OperationStatus value, buffer operators, 458–463

operators

conversion operators, 198-C05.1827

equality operators

reference types, 328

usage guidelines, 324–328

value types, 327

inequality operators, 200–202

method names and, 196–197

overloading, 192–198

optional features, design patterns, 408–411

optional parameters, changing

default values, 552

to required, 551–552

required parameters to optional, 551

organization (files), C# style conventions, 483–485

Out parameters, 512

OutOfMemoryException, 277–278

overload operator parameters, naming conventions, 80

overloading

members, 136–148, 544–545

operators, 192–198

override members

adding to unsealed types, 540

removing

removing an override of a virtual member, 543

removing an override of an abstract member, 543–544

P

packages, naming conventions, 61–62

parameters

argument validation, 207–210

boolean parameters, choosing, 205–207

collection parameters, 296–297

designing, 202–204

enum parameters, choosing, 205–207

members with variable number of parameters, 214–218

method parameters

adding, 546

changing types, 546

removing, 546

renaming, 545

reordering parameters by the same type, 547

reordering parameters of differing types, 547

naming conventions, 79–80

optional parameters, changing

default values, 552

required parameters to optional, 551

to required, 551–552

Out parameters, 512

overload operator parameters, naming conventions, 80

passing, 210–214, 549–550

pointer parameters, 218–219

Ref parameters, 512

reference parameters

Async variants of existing synchronous methods, 352–353

changing, 549–550

required parameters, changing

optional parameters to, 551–552

to optional, 551

Pareto principle, 10

partial writes to buffers, 458–463

PascalCasing, 42–44

C# style conventions, 480–481

naming conventions, 480–481

passing parameters, 210–214

passive voice, comments, 483

performance, exceptions, 281

Tester-Doer Pattern, 281–282

Try Pattern, 282–286

.Permissions subnamespaces, 489–490

personification, comments, 483

PlatformNotSupportedException, 279

pointer parameters, 218–219

predetermined buffer sizes, 451–452

private fields

removing, on serializable types, 544

renaming, in serializable types, 544

programming

languages, framework design, 11–12

OOP, 7–8

progress reporting, Async Patterns, 513–516

progressive frameworks, 12–15

properties

auto-implemented properties, 479

change notification events, 163–165

designing, 158–160

change notification events, 163–165

indexed properties, 161–163

indexed properties, designing, 161–163

member properties, choosing, 152–158

naming conventions, 75–76

events, 77–78

fields, 78–79

methods, 74–75

properties, 75–76

types, changing, 548

protected members, extensibility, 230

prototyping, well-designed frameworks, 2

Q - R

query patterns, LINQ support, 404–408

RAD (Rapid Application Development), progressive frameworks, 13

readability, naming conventions, 52

readonly modifiers

C# style conventions, 479

structs

adding to, 535, 550

removing from, 535–536, 551

recompile breaks, 530

Ref parameters, 512

ref structs, 538

reference parameters

Async variants of existing synchronous methods, 352–353

changing, 549–550

reference types

equality operators, 328

fields, adding to structs, 540

Object.Equals, 314

reflection breaks, 530

rehydration, Dispose Patterns, 381–382

removing

finalizers

from sealed types, 542

from unsealed types, 542

method parameters, 546

non-override members, 543

override members

removing an override of a virtual member, 543

removing an override of an abstract member, 543–544

private fields, on serializable types, 544

readonly modifiers from structs, 535–536, 551

static modifiers, 549

types, 533

renaming

assemblies, 530–531

method parameters, 545

private fields in serializable types, 544

reordering method parameters

of differing types, 547

by the same type, 547

reporting (progress), Async Patterns, 513–516

required parameters, changing

to optional, 551

optional parameters to, 551–552

return types

Async methods, 348–351

method return types, changing, 547–548

return values in collections, 298–302

runtime breaks, 529

runtime error exceptions, changing to usage error exceptions, 553–554

runtime serialization, 493, 500–502

S

scenario-driven framework design, 16–23

scoped operations, Dispose Patterns, 387–391

sealed types

removing finalizers from, 542

unsealing, 534

sealing,

extensibility, 244–246

unsealed types, 534

SEHException, 278

self-documenting object models, principle of, 29–30

abstractions, 34–36

consistency, 34

exceptions, 33

layered architecture, principle of, 36–37

naming, 30–32

strong typing, 33–34

serializable types, private fields, 544

serialization

Binary serialization, 493

Data Contract serialization, 493, 495–499

.NET serialization technologies, 493

obsolete guidance, 493–502

runtime serialization, 493, 500–502

SOAP serialization, 493

usage guidelines, 319–321

XML serialization, 493, 499–500

signatures (member)

changing, 545–553

tuples in, 220–226

simplicity, well-designed frameworks, 3–4

single-line syntax (// .), comments, 482

snapshot collections, 301–302

SOAP serialization, 493

source-breaking changes

compilation breaks, 530

recompile breaks, 530

spaces, C# style conventions, 469–470

Spans, 11–12, 431–445

specifications

sample specification, 523–528

Stopwatch specification, 524–528

StackOverflowException, 276–277

static classes

defined, 84

type design guidelines, 102–104

static modifiers, adding/removing, 549

static TryParse methods, 286

Stopwatch specification, 524–528

strings (strongly typed), 129–133

strong typing, self-documenting object models (principle of), 33–34

structs

adding first reference type field to, 540

changing

changing classes to, 537

to classes, 537–538

DateTime struct, 306–308

DateTimeOffset struct, 306–308

defined, 84

ICloneable struct, 308–309

IComparable<T> struct, 309–311

naming conventions, 67–70

common types, 71

enumerations, 72–74

generic type parameters, 70–71

Nullable<T> struct, 311–312

readonly modifiers

adding to structs, 535, 550

removing from structs, 535–536, 551

ref structs, 538

type design guidelines, 89–92, 106–111

usage guidelines

DateTime struct, 306–308

DateTimeOffset struct, 306–308

ICloneable struct, 308–309

IComparable<T> struct, 309–311

Nullable<T> struct, 311–312

ValueTask structs, Async Patterns, 358–359

ValueTask<TResult> structs, Async Patterns, 358–359

style conventions, C#465–466

ASCII characters, code restrictions, 479

assignment-expression-throw, 480

auto-implemented properties, 479

BCL type names, 476

braces ({ }), 466–469

collection initializers, 478

commas ( , ), 475–476

comments, 482–483

expression-bodied members, 478–479

file organization, 483–485

if.throw, 480

indents, 465–466

language keywords, 476

member modifiers, 473–475

nameof (.) syntax, 479

naming conventions, 480–482

object initializers, 477–478

readonly modifiers, 479

spaces, 469–470

this.476

Unicode escape sequences (uXXXX), 479

var keyword, 476–477

vertical whitespace, 472–473

subclassing, 13

subnamespaces

.Design subnamespaces, 489

.Interop subnamespaces, 490

naming conventions, 489–490

.Permissions subnamespaces, 489–490

SuppressFinalize method, Dispose Patterns, 378

synchronous methods, Async variants of, 353–354

SystemException, 274

System.Object, usage guidelines, 312

Object.Equals, 312–314

Object.GetHashCode, 315–316

Object.ToString, 316–318

System.Uri

implementation guidelines, 322–323

usage guidelines, 321–323

System.Xml, usage guidelines, 323–324

T

Task-Based Aync Pattern, 341–347

TaskCanceledException, 278

Task.Status, consistency, 355–357

technology namespace groups, 66–67

Template Method Pattern, 423–425

Tester-Doer Pattern, exceptions and performance, 281–282

this., C# style conventions, 476

throwing exceptions, 254–260

choosing exceptions, 260–264

error messages, 264–265

from existing thrown types, 555

new types of error exceptions, 555

timeouts, 426–427

trade-offs, well-designed frameworks, 6

Try Pattern, exceptions and performance, 282–284

static TryParse methods, 286

value-producing Try methods, 284–285

Try-Write Pattern, 452–458

tuples in member signatures, 220–226

types

abstractions, extensibility, 239–241

assemblies

metadata and types, 127–129

renaming, 530–531

classes

abstract classes, 98–102

defined, 84

static classes, 102–104

type design guidelines, 89–104

common types, naming conventions, 71

constructors, 172–175

derived types, moving members to, 542

design guidelines, 84–85

assembly metadata and types, 127–129

classes, 89–104

enums, 111–124

interfaces, 92–100, 104–106

namespaces, 85–88

nested types, 124–127

strongly typed strings, 129–133

structs, 89–92, 106–111

enums

adding values to, 123–124

defined, 84

flag enums, 119–123

type design guidelines, 111–124

exception types, 273–279

factored types, aggregate components, 334–335

finalizable types, Dispose Patterns, 383–387, 511–517

interfaces

defined, 84

type design guidelines, 92–100, 104–106

logical groupings, 83

members

moving to derived types, 542

naming conventions, 79

method parameter types

changing, 546

reordering parameters of differing types, 547

moving

via [TypeForwardedTo], 532–533

without [TypeForwardedTo], 533

names

case sensitivity, 534

changing namespaces, 535

namespaces

adding namespaces that conflict with existing types, 531–532

name conflicts, 65–67

obsolete guidance, 489–490

type design guidelines, 85–88

nested types, design guidelines, 124–127

parameters (generic), naming conventions, 70–71

property types, changing, 548

reference types

equality operators, 328

Object.Equals, 314

removing, 533

return types

Async methods, 348–351

changing method return types, 547–548

sealed types

removing finalizers from, 542

unsealing, 534

sealing unsealed types, 534

serializable types, private fields

removing, 544

renaming, 544

static classes, defined, 84

strings (strongly typed), 129–133

structs

defined, 84

type design guidelines, 89–92, 106–111

unsealed types

adding members to, 539–540

removing finalizers from, 542

value types, 99

equality operators, 327

Object.Equals, 314

values returned type, changing from a method, 554–555

typing (strong), self-documenting object models, 33–34

U

underscores (_), naming conventions, 53, 481–482

unhandled exception handlers, 253

Unicode escape sequences (uXXXX), C# style conventions, 479

unsealed classes, extensibility, 228–229

unsealed types

adding members to, 539–540

removing finalizers from, 542

sealing, 534

Uri

implementation guidelines, 322–323

usage guidelines, 321–323

usability studies, designing frameworks, scenario-driven framework design, 21–23

usage error exceptions, changing

to functioning behavior, 554

runtime error exceptions to, 553–554

usage guidelines

arrays, 287–291

attributes, 291–294

collections, 294–296

arrays versus collections, 302–303

custom collections, 302–303

live collections, 301–302

parameters, 296–297

properties, 298–302

return values, 298–302

snapshot collections, 301–302

DateTime struct, 306–308

DateTimeOffset struct, 306–308

equality operators, 324–328

ICloneable struct, 308–309

IComparable<T> struct, 309–311

Nullable<T> struct, 311–312

Object.Equals, 312–314

reference types, 314

value types, 314

Object.GetHashCode, 315–316

objects, 312

Object.Equals, 312–314

Object.GetHashCode, 315–316

Object.ToString, 316–318

Object.ToString, 316–318

serialization, 319–321, 493–502

structs

DateTime struct, 306–308

DateTimeOffset struct, 306–308

ICloneable struct, 308–309

IComparable<T> struct, 309–311

Nullable<T> struct, 311–312

System.Object, 312

Object.Equals, 312–314

Object.GetHashCode, 315–316

Object.ToString, 316–318

System.Uri, 321–323

System.Xml, 323–324

Uri, 321–323

uXXXX (Unicode escape sequences), C# style conventions, 479

V

validation

arguments, 207–210, 480

assignment-expression-throw, 480

DP, 370

value coercion, DP, 371–372

value types, 99

equality operators, 327

Object.Equals, 314

value-producing Try methods, 284–285

values

constant field values, changing, 552

default values, changing in optional parameters, 552

values returned type, changing from a method, 554–555

ValueTask structs, Async Patterns, 358–359

ValueTask<TResult> structs, 358–359

var keyword, C# style conventions, 476–477

vertical whitespace, C# style conventions, 472–473

virtual members

abstract members, changing to virtual members, 553

changing

to abstract members, 553

non-virtual members to, 553

extensibility, 237–239

override members, removing an override of a virtual member, 543

visibility of members, changing, 548–549

Visual Basic, language-specific names, 57

W

“we” in comments, 483

well-designed frameworks, qualities of, 3

backward compatibility, 2

consistency, 7–8

evolution, 7

existing proven designs, borrowing from, 6–7

expense, 4–5

integration, 7

OO design, 2

prototyping, 2

simplicity, 3–4

trade-offs, 6

whitespace (vertical), C# style conventions, 472–473

word choice, naming conventions, 52–55

wrapping exceptions, 271–273

X - Y - Z

XAML readable types, 427–430

XML serialization, 493, 499–500