SDK Conventions

Skill: .NET SDK Conventions

Reviewing Generated Output

When reviewing a service migration's generated output, open and diff every single generated file — every operation's request marshaller and response unmarshaller, every model, exception, and client file. No sampling. Reviewing one operation and generalizing "clean" to its neighbors is how regressions ship. Thousands of files is not a reason to skip any.

The public API surface can be identical while the wire behavior changes. AssemblyComparer and "the public surface is unchanged" only check the public contract; they cannot see marshaller/unmarshaller bodies — ResourcePath, query parameters, headers, serialization. A clean AssemblyComparer is necessary, not sufficient; it is not a substitute for reading the diff.

A removed line in generated output is a red flag — investigate it, do not wave it through. Real example: the generator dropping request.AddSubResource("aws_iam", "t") and folding the query literal into request.ResourcePath = "/token?aws_iam=t" left the public API identical while silently changing the request sent to the wire (? gets percent-encoded, dropping the flag).

What Must Match (Public API Contract)

• Public class/interface names and their base types. An event structure (a non-error member of a @streaming union) implements Amazon.Runtime.EventStreams.IEventStreamEvent, fully qualified (no using) so it can't clash with a per-stream {Namespace}.Model.IEventStreamEvent. A request event stream's input member becomes a Func<Task<I{Union}Event>> {Member}Publisher property: it keeps any modeled [AWSProperty]/[Obsolete] but has no IsSet (the marshaller wires the Func unconditionally). Its doc content matches C2J.
• Public property names, types, and nullability
• Public method signatures (name, parameters, return type)
• [AWSProperty] attributes on public members (Required, Min, Max)
• XML doc comments on public types and members (content, not formatting)
• partial modifier on all generated types
• Namespace structure ({Namespace}, {Namespace}.Model)
• internal bool IsSet{Property}() per member — the public AWSSDKUtils.IsPropertySet reflection API and existing marshallers invoke these by name

What Can Differ

• Whitespace, indentation, blank lines (the Roslyn formatter runs on every C# file whose raw output differs from the file on disk; emitting exact spacing lets a run skip it)
• File names — prefer {TypeName}.g.cs to distinguish generated files
• Backing fields and other private helpers (the generator omits them — see Property Pattern below)
• using directive order
• #region blocks (purely cosmetic)
• Code comments outside XML docs

Pragma Warnings

The SDK builds with warnings-as-errors. Generated files must include #pragma warning disable for warnings that would otherwise break the build. The exact set doesn't need to match the current SDK file-for-file, but the output must compile cleanly. Common ones:

• CS0612 / CS0618 — obsolete/deprecated member usage (generated code may reference deprecated shapes)
• CS1570 — malformed XML doc comments (common with complex HTML from @documentation traits)

License Header

Every generated file starts with the full Apache 2.0 license block followed by the "Do not modify this file. This file is generated from the {model-filename} service model." notice, where {model-filename} is the Smithy model file name (e.g. cloudtrail-data-2021-08-11.normal.json). The exact text lives in Writers/FileHeader.cs.

Naming Rules

Which Name Goes Where

A service has two derived names, equal for most services:

• BaseName (C2J ClassName, metadata.json's base-name) → the generated type names: client, config, exception/request bases, endpoint types. Model classes go in {Namespace}.Model.
• ServiceName (C2J ServiceFolderName, the namespace minus Amazon.) → everything else: AWSSDK.{X} package names, sdk/src|test/Services/{X} trees, _sdk-versions.json keys, {X}.slnx, the endpoint tests [TestCategory], and the paginator factory types (I{X}PaginatorFactory — C2J's templates use ServiceNameRoot there).

They diverge when metadata.json overrides the namespace: sesv2 has class AmazonSimpleEmailServiceV2Client but package/folder/paginators SimpleEmailV2. When adding a name to a writer, check the shipping SDK for which of the two it follows.

Class and Member Names

• Shape names → PascalCase class names (Smithy shape names are already PascalCase). The service rename map wins when it has an entry for the shape; error codes still use the shape name
• Member names → PascalCase property names. Smithy uses camelCase (eventData), .NET uses PascalCase (EventData)
• The conversion: capitalize the first letter of the Smithy member name
• Acronyms are preserved as-is from the Smithy model. Example: eventID → EventID (not EventId)
• A response member named ContentLength is omitted from the response class — AmazonWebServiceResponse already declares it — but the response unmarshaller still assigns the inherited property. Response-only, matching C2J (the MediaStoreData case).

Client Names

• Interface: IAmazon{BaseName} (e.g. IAmazonCloudTrailData)
• Class: Amazon{BaseName}Client (e.g. AmazonCloudTrailDataClient)
• Config: Amazon{BaseName}Config
• Service exception base: Amazon{BaseName}Exception
• Service request base: Amazon{BaseName}Request

File Layout

Generated files go under Generated/. Prefer .g.cs suffix:

Generated/
  IAmazon{BaseName}.g.cs
  Amazon{BaseName}Client.g.cs
  Amazon{BaseName}Config.cs            # plain .cs so CI's Amazon*Config.cs glob stages it
  Amazon{BaseName}Exception.g.cs
  Model/
    Amazon{BaseName}Request.g.cs       # empty service request base
    {OperationName}Request.g.cs
    {OperationName}Response.g.cs
    {ShapeName}.g.cs
    {ExceptionName}.g.cs

A structure that doubles as an operation input/output normally gets only its {Op}Request/{Op}Response wrappers — no {ShapeName}.g.cs. Exception: when other generated code references the shape through a member (directly or as a list/map element), the standalone class is emitted too, because member properties are typed with the plain class name (C2J parity: drs SourceServer has one, kinesis EnhancedMonitoringOutput does not).

Doc Samples

DocSamplesWriter and DocSampleMetadataWriter emit docgenerator/AWSSDKDocSamples/{ServiceName}/{ServiceName}.GeneratedSamples.cs and {ServiceName}.GeneratedSamples.extra.xml from smithy.api#examples, rendering values as C2J's Example.cs does but with the SDK's types, so a copied sample compiles once placeholders like <data> are filled in. Both are written unformatted (BatchGenerator passes format: false): the samples file is never compiled and can hold placeholders like <binary data> that the Roslyn formatter would mangle. A service with no examples, or S3 (its samples are hand-written), gets no files, so an existing sample file stays as it is; examples the model lacks but C2J had are a model gap. Example keys are matched to members (TypeMapper.ResolveMembers) ignoring case after CustomizationTransform, so, as in C2J, a member renamed by emitPropertyName (beyond case) drops out of the sample. The samples are built before anything is written, so a bad example fails the service before anything is deleted, and written only once its code has generated.

Differences from C2J:

• Region ids are {Operation}-{n} (the trait has no example id). They only link an .extra.xml entry to its code. Each is unique, unlike C2J's repeated example-1, which made the docs build (it takes the first matching #region) show the first sample's code for every later one.
• Keys are written ordinal-sorted; examples.json's order is sorted for about 92% of objects.
• Which examples exist, and their order within an operation, follow the trait.
• examples.json comments (C2J's // comment after an assignment) are lost: the trait has no such field.
• Response locals are typed as the response properties are (int?, Stream, the enum's class); C2J used non-nullable scalars, MemoryStream and string. Locals that are C# keywords are escaped (@event).
• A timestamp prints its 24-hour time and milliseconds, and a number is read as epoch seconds (or DateTime.UtcNow if it's out of range); C2J printed a 12-hour hour, dropped milliseconds and wrote DateTime.UtcNow for any number. A fractional float gets f.
• A request event stream is omitted: its Func publisher property can't be written from example data.
• A document value renders as global::Amazon.Runtime.Documents.Document with its content, using its collection initializer; C2J rendered an empty initializer of a class that doesn't exist.
• String literals are fully C# escaped, and titles and documentation escape &, < and > (titles also ") and drop characters XML 1.0 can't carry; C2J escaped only quotes, so a backslash, newline or & produced broken code or XML.
• The writers' own layout follows CodeWriter (platform newlines, 2-space XML indent); documentation text is written as it is. The docs build parses the XML and left-justifies each region, so the rendered docs don't change.

Event Streams

Protocol-independent; only the per-event payload (un)marshalling and the response unmarshaller's body differ (see marshalling). Each @streaming union is emitted once, however many operations share it.

Request (union sent as an operation input):

• Gets the marker interface I{Union}Event plus a {Event} : I{Union}Event partial per event. The name comes from the union, never the operation (shipped: Lex V2 IStartConversationRequestEventStreamEvent), and is emitted once per union even when several operations send it (the protocol test client shares one union across four).
• @error members get no partial: a client never sends an error event.

Response (union returned as an operation output):

• {Union} is emitted as the EnumerableEventOutputStream<RuntimeEvent, {BaseName}EventStreamException> subclass (C2J parity; RuntimeEvent is the alias described under Both). Each union member is a mapping entry keyed on the member name verbatim (the wire :event-type; the dict is OrdinalIgnoreCase): @error members feed ExceptionMapping, the rest EventMapping plus a PascalCase {Name}Received handler. The union gets no plain model class and no structure unmarshaller (the response unmarshaller does new {Union}(context.Stream)); its events keep theirs.
• The {Op}Response implements IDisposable and its dispose pattern releases the event stream member. Only when the operation also sends an event stream (bidi, or input-only) does it implement Amazon.Runtime.EventStreams.IEventInputStreamContextOwner (explicit SetEventInputStreamContext under a CA1033 suppression) and dispose the context first (C2J parity: Bedrock ConverseStreamResponse is AmazonWebServiceResponse, IDisposable, Lex V2 StartConversationResponse adds the owner interface).
• Any response event stream gates the per-service {BaseName}EventStreamException.

Both:

• Names are never adjusted for collisions: the protocol test client's union is named EventStream, so its marker is IEventStreamEvent, same simple name as the runtime's (the only runtime type an I{Union}Event can shadow). Anywhere under the .Model namespace (model classes, MarshallTransformations) the service's marker silently wins over the import; files outside it that import both namespaces (the client) hit CS0104. Every writer that needs the runtime's emits using RuntimeEvent = Amazon.Runtime.EventStreams.IEventStreamEvent; and uses RuntimeEvent. An alias named IEventStreamEvent would not help (a type in an enclosing namespace beats it too); one no shape can be named after does.

Base Types

All Types Are partial

Every generated class and interface uses the partial modifier.

Property Pattern

The public surface must match. Internal implementation can vary.

Required public surface:

/// <summary>
/// Gets and sets the property EventData. 
/// <para>
/// The content of an audit event...
/// </para>
/// </summary>
[AWSProperty(Required=true)]
public string EventData { get; set; }

/// <summary>
/// Checks to see if the EventData property is set.
/// </summary>
internal bool IsSetEventData() => this.EventData != null;

The generator emits auto-properties ({ get; set; }) plus an internal IsSet{Property}() method per member. The current SDK uses explicit backing fields, but the public surface (and the reflection API) only needs the property and the IsSet method — a backing field is not required.

Exception — emitIsSetProperties customization. A listed member (shape name → modeled member names) also gets a public bool Is{Property}Set { get; set; } whose accessors call InternalSDKUtils.GetIsSet/SetIsSet(value, ref field). A property can't be passed by ref, so the member gets a private _{Property} backing field (collections keep the InitializeCollections initializer) instead of an auto-property. IsSet{Property}() returns Is{Property}Set. Only nullable value types and collections have SetIsSet overloads; any other listed member throws. Doc text matches C2J's StructureGenerator.tt.

[AWSProperty] attribute rules:

• Required=true when member has @required trait, unless it also carries @idempotencyToken (the SDK fills it)
• Min=N when member has @length trait with min, or @range trait with min
• Max=N when member has @length trait with max, or @range trait with max
• Omit the attribute entirely if none of these traits are present