.NET Client Patterns: Service description for bytes upload should generate client following unbranded .NET client patterns

[annelo-msft]

TypeSpec file:

import "@typespec/http";
import "@typespec/rest";

@service({
    title: "PutBytes",
  })

  namespace PutBytes;

  using TypeSpec.Http;
  using TypeSpec.Rest;

  interface PutBytesClient {
    @put @route("upload") Upload(document: bytes) : void;
  }

Expected client output

• Client should have a public constructor that takes endpoint and client options
• Client constructor should validate arguments, assign endpoint, create options if needed, and create pipeline
• Convenience methods should take CancellationToken parameters
• Model types should not be defined or used if BinaryContent can be created directly from input
• Protocol methods should take a nullable RequestOptions parameter. Should be optional where parameter types are different from convenience overloads.
• Rest file should only create instances of classifiers used by the client
• Rest file should not re-allocate a classifier that has already been allocated
• Request creation helpers should use correct status code classifier for PUT (200 or 201, see Azure API Guidelines)
• Request creation helpers should add correct header type (Content-Type should be application/octet-stream for byte uploads)
• Emitted internal helper files should not have methods that aren't used by the client
• Emitted internal helper files should be added if needed by the client
• Nullable annotations should be used
• No subclient factory method should be added when there are no subclients
• No internal constructors should be added when they are not called
• (would be nice) use file scoped namespace declarations

A diff of expected generator output compared to current generator output is here: https://github.com/annelo-msft/typespec/pull/2

[JoshLove-msft]

Currently in order to generate the content type and a binary upload method that doesn't serialize a model, the tsp would need to look like this - note we add the contentType header and body decorator:

  interface PutBytesClient {
    @put @route("upload") Upload(@header contentType: "application/octet-stream", @body document: bytes) : void;
  }

[JoshLove-msft]

/cc @schaabs for thoughts on the tsp requirements mentioned in previous comment.

[annelo-msft]

Adding the context that @KrzysztofCwalina raised the concern with me directly that those decorators would need to be added to obtain a client that used the headers and didn't write those models.

I am happy to defer to @schaabs and @KrzysztofCwalina regarding whether that is the TypeSpec we would like customers/partners to need to write in order to have our .NET generator write a client that can upload application/octet-stream bytes to a service. For me personally, I would wonder the following about:

@put @route("upload") Upload(document: bytes) : void;

1. When does it make sense that this TypeSpec would use application/json ContentType header? Is it common?
   • My thinking with this question is -- ideally the most common desired outcome would map to the simplest TypeSpec. It would be preferable if TypeSpec authors needed to write more TypeSpec to satisfy uncommon scenarios, rather than the inverse
2. Does it make sense that bytes would need a model to support it for the most common case?
   • My thinking here is that we have .NET types (in BCL, Azure.Core, and SCM) that map to bytes. Ideally, these would be used to represent the input parameters of the client method for this service operation in the most common case. Model types make sense when more than this is needed (to provide what is essentially a POCO to group primitives and other BCL/Core types that need to be assembled to write the content of a request to send to the service). If a TypeSpec type has a corresponding .NET BCL/Core type, I am not sure I see the benefit of adding a model to the public API for that -- or having an internal type to wrap it, since that would add performance overhead in terms of allocations and possibly CPU time as well.

[JoshLove-msft]

As part of determining the tsp -> C# story, we should keep in mind what the experience would look like across other language generators. It would be odd if a single tsp generated semantically different clients across the languages that we support, which makes me wonder if these type of inferences would be better to make further upstream in TCGC so that all the language emitters get it for free.