Inndata (.proto-skjema)

Utdata (C#)

Hva dette verktøyet gjør

Du har et Protocol Buffers-skjema og en C#-tjeneste eller -klient som trenger de matchende DTO-ene. Den offisielle veien er å installere protoc med C#-pluginen (eller koble Grpc.Tools inn i .csproj-en din) og la MSBuild generere partial-klassene under bygging. Det funker, men det er overkill når du bare vil lese skjemaet, skissere typer eller lime inn en message i en Razor-side eller en engangsintegrasjon. Denne konvertereren gjør samme type jobb — lim inn, kopier, slipp inn i Types.cs.

Type-mappingen er av den kjedelige-men-korrekte sorten. string forblir string (med initialiseren = "" så prosjekter med nullable references ikke klager). bool, int32, int64, uint32, uint64, float, double mapper til henholdsvis bool, int, long, uint, ulong, float, double. bytes blir til byte[]. repeated T blir til List<T>, map<K, V> blir til Dictionary<K, V>, og kjente wrappers som google.protobuf.Timestamp skrives ut som string (proto3 JSON-kodingen for tidsstempler er RFC 3339, som på wire-nivå bare er en streng — se proto3 JSON-spesifikasjonen hvis du vil ha detaljene).

Feltnavn får standard PascalCase-behandlingen — order_id → OrderId, shipping_address → ShippingAddress — som matcher det den offisielle C# protobuf-referansen genererer. Enum-verdier mister SCREAMING_SNAKE-prefikset sitt når skjemaet følger konvensjonen om å prefikse hver verdi med enum-navnet (så ORDER_STATUS_PENDING i enum OrderStatus blir OrderStatus.Pending). Utdata-klassene er flate — alle nøstede messages løftes opp til top-level, så du kan splitte eller flytte rundt på dem uten å rive opp scopes. Konverteringen skjer i sin helhet i nettleseren din; ingenting fra skjemaet lastes opp.

Slik bruker du det

Tre steg. Utdataen er klar til å kompileres — lim den inn i en <code>Types.cs</code>-fil i prosjektet ditt.

Lim inn .proto-skjemaet ditt

Slipp skjemaet inn i editoren til venstre. syntax = "proto3"; i toppen er valgfritt. Parseren håndterer nøstede message-blokker, enum-deklarasjoner, oneof, map<K, V>, feltopsjoner og de vanlige package/import/option-direktivene. Imports gjenkjennes, men hoppes over — så lim inn importerte typer inline hvis skjemaet ditt avhenger av dem.

Konverteringen av feltnavn skjer automatisk: customer_name i .proto blir CustomerName i C#. Klasse- og enum-navn lar vi være som de er (per konvensjon allerede PascalCase).

Les utdataen

Til høyre: public class-deklarasjoner med { get; set; }-auto-properties for hver message, pluss public enum-deklarasjoner for hver enum. En using System.Collections.Generic;-linje legges til når skjemaet bruker repeated- eller map-felter (slik at List og Dictionary kan resolve). Slipp filen inn i et prosjekt, pakk det inn i din namespace, ferdig.

Koble det opp

For ren DTO-bruk er klassene klare til å serialiseres med System.Text.Json eller Newtonsoft.Json. For ekte gRPC C#-arbeid — tjeneste-implementasjoner, streaming, deadlines — fortsett å bruke Grpc.Tools for wire-format-typene, og bruk denne konvertereren til håndskrevne wrappers, mapping-lag eller test-fixturer ved siden av den genererte koden.

Når dette faktisk sparer tid

Skissere DTO-er for en ny gRPC-tjeneste

Du starter en ASP.NET Core gRPC-tjeneste og vil se hvordan messages kommer til å se ut i C# før du forplikter deg til Grpc.Tools. Lim inn .proto-en, kikk på klassene, vurder om feltnavngivningen passer til teamets stil, og koble så codegen ordentlig opp.

Håndskrevet mapping-lag

De genererte gRPC-typene dine bor i sin egen namespace, og du vil ha rene DTO-er for domenelaget. Utdataen her gir deg pene klasser uten metadata-rotet fra generert kode — enkelt å mappe frem og tilbake med AutoMapper eller egne konvertere.

Gjennomgå en Protobuf-skjemaendring

En lagkamerat la til felter i en message i en PR. Du vil se konsekvensene for C#-formen uten å sjekke ut branchen og kjøre et build. Lim inn det nye skjemaet, gjør diff mot de nåværende C#-typene, og legg igjen en målrettet review-kommentar.

Test-fixturer og raske skript

Du skriver et engangs LinqPad-skript eller en konsoll-app som POST-er til en gRPC-gateway. Å rigge hele Protobuf-toolchainen for 50 linjer testkode er overkill. Hent klassene herfra, serialiser dem til JSON, send requesten, og gå videre.

Vanlige spørsmål

Sendes skjemaet mitt noen steder?

Nei. Parseren og C#-emitteren kjører i sin helhet i nettleseren din som JavaScript. Åpne DevTools og se på Network-fanen mens du limer inn — null requests. Praktisk når skjemaet ditt inneholder interne typenavn, package-stier eller noe annet du ikke vil sende til en tredjepart.

Funker disse klassene med Grpc.Tools-generert kode?

De produserer ekvivalente former, men ikke byte-for-byte identiske. Grpc.Tools genererer partial-klasser, parser-registreringer, descriptor-tilkobling og forfar-typer fra Google.Protobuf.IMessage — ingenting av det er her. For ekte gRPC-wire-protokoll-arbeid: bruk Grpc.Tools. For kun-DTO-kode (f.eks. JSON-over-HTTP-gateways, mapping-lag, testdata) holder dette outputtet helt fint.

Hvorfor er int64 og uint64 typet som long og ulong i stedet for string?

Fordi de passer i C#. I motsetning til JavaScript-Numbers (som mister presisjon over 2^53), håndterer C#-long hele int64-rekkevidden nativt, så det er ingen grunn til å falle tilbake til string. Hvis du deserialiserer proto3-JSON der 64-bits ints kommer som strenger (etter JSON-mapping-spesifikasjonen), tar System.Text.Json med JsonNumberHandling.AllowReadingFromString seg av konverteringen.

Hvordan håndteres SCREAMING_SNAKE-konvensjonen for enum-verdier?

Protobufs style guide anbefaler å prefikse hver enum-verdi med enum-navnet i SCREAMING_SNAKE. Konvertereren oppdager det og fjerner prefikset. ORDER_STATUS_UNSPECIFIED i enum OrderStatus blir til OrderStatus.Unspecified. Hvis enum-en din ikke følger konvensjonen (noen verdier prefikset, andre ikke), hoppes prefiks-strippingen over og verdiene PascalCase-es som de er.

Håndterer den oneof?

Hvert oneof-felt skrives ut som en vanlig auto-property. Outputtet håndhever ikke "nøyaktig én"-kravet som oneof innebærer — språket C# har ennå ikke native discriminated unions. Trenger du strengere modellering, kikk på biblioteker som OneOf på NuGet, eller rediger outputtet manuelt til en baseklasse pluss subklasser.

Hva med google.protobuf.Timestamp og well-known types?

Timestamp skrives ut som string (proto3-JSON koder tidsstempler som RFC 3339-strenger). Empty og Any blir til object-plassholdere — juster til Google.Protobuf.WellKnownTypes.Any eller en sterkere type hvis prosjektet ditt drar inn WKT-pakken. Outputtet er bevisst framework-fritt, så du kan slippe det inn i et hvilket som helst C#-prosjekt uten å tvinge frem en NuGet-avhengighet.

Relaterte verktøy

Hvis du jonglerer mellom Protobuf, JSON og C#, passer disse godt sammen:

Protobuf til C#-konverterer