{"id":15286023,"url":"https://github.com/dtanglr/primitively","last_synced_at":"2025-10-26T17:03:32.109Z","repository":{"id":62910528,"uuid":"480590016","full_name":"dtanglr/Primitively","owner":"dtanglr","description":"Primitively is a powerful C# source generator that transforms primitive identifiers and value objects into highly performant, customisable, read-only struct values that support ASP.NET model binding and validation (including FluentValidation), Open API standards, JSON and MongoDB BSON serialization, with zero or minimal configuration. ","archived":false,"fork":false,"pushed_at":"2024-12-01T03:34:34.000Z","size":1341,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T03:07:47.333Z","etag":null,"topics":["asp-net-core","aspnet-mvc","aspnetcore","bson","csharp","dotnet","fluentvalidation","mongodb","obsession","open-api","primitive","primitive-obsession","primitives","source-code-generator","strongly-typed-id","swagger","type-safe","value-object"],"latest_commit_sha":null,"homepage":"https://primitively.net/","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dtanglr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-11T23:53:06.000Z","updated_at":"2025-04-01T23:49:36.000Z","dependencies_parsed_at":"2024-03-22T04:31:28.719Z","dependency_job_id":"1c2c408f-dcf8-4ed0-b29d-1fbdb5a1ccca","html_url":"https://github.com/dtanglr/Primitively","commit_stats":{"total_commits":386,"total_committers":2,"mean_commits":193.0,"dds":"0.020725388601036232","last_synced_commit":"c95d65771a41ce19968843f546f970f1404f4873"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtanglr%2FPrimitively","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtanglr%2FPrimitively/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtanglr%2FPrimitively/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtanglr%2FPrimitively/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dtanglr","download_url":"https://codeload.github.com/dtanglr/Primitively/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248657918,"owners_count":21140846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asp-net-core","aspnet-mvc","aspnetcore","bson","csharp","dotnet","fluentvalidation","mongodb","obsession","open-api","primitive","primitive-obsession","primitives","source-code-generator","strongly-typed-id","swagger","type-safe","value-object"],"created_at":"2024-09-30T15:09:48.818Z","updated_at":"2025-10-26T17:03:32.018Z","avatar_url":"https://github.com/dtanglr.png","language":"C#","readme":"![Primitively](docs/images/logo-143x153.png)\n\n# Primitively  [![CI](https://github.com/dtanglr/Primitively/actions/workflows/dotnet.yml/badge.svg?branch=main)](https://github.com/dtanglr/Primitively/actions/workflows/dotnet.yml)\n\n**Primitively** is a Rosyln-powered C# source code generator of strongly-typed IDs and DDD-style value objects encapsulating a single GUID, integer, date or string .NET *primitively* typed value.\n\nFor example: - \n\n```csharp\n// Before\npublic record Product(Guid Id, Guid Sku);\n\n// After\npublic record Product(ProductId Id, Sku Sku);\n\n[Guid]\npublic partial record struct ProductId;\n\n[Guid]\npublic partial record struct Sku;\n```\n\n## NuGet Packages\n\n| **Package** | **Latest Version** | **About** |\n|:--|:--|:--|\n| `Primitively` | [![NuGet](https://buildstats.info/nuget/Primitively?includePreReleases=true)](https://www.nuget.org/packages/Primitively/ \"Download Primitively from NuGet.org\") | The Primitively source generator package. |\n| `Primitively.Abstractions` | [![NuGet](https://buildstats.info/nuget/Primitively.Abstractions?includePreReleases=true)](https://www.nuget.org/packages/Primitively.Abstractions/ \"Download Primitively.Abstractions from NuGet.org\") | Primitively interfaces, metadata, attributes and configuration classes. |\n| `Primitively.AspNetCore.Mvc` | [![NuGet](https://buildstats.info/nuget/Primitively.AspNetCore.Mvc?includePreReleases=true)](https://www.nuget.org/packages/Primitively.AspNetCore.Mvc/ \"Download Primitively.AspNetCore.Mvc from NuGet.org\") | ASP.NET MVC model binding support for Primitively types used in route and query string parameters. |\n| `Primitively.AspNetCore.SwaggerGen` | [![NuGet](https://buildstats.info/nuget/Primitively.AspNetCore.SwaggerGen?includePreReleases=true)](https://www.nuget.org/packages/Primitively.AspNetCore.SwaggerGen/ \"Download Primitively.AspNetCore.SwaggerGen from NuGet.org\") | Swagger Open API schema support is available for Primitively types using Swashbuckle. |\n| `Primitively.FluentValidation` | [![NuGet](https://buildstats.info/nuget/Primitively.FluentValidation?includePreReleases=true)](https://www.nuget.org/packages/Primitively.FluentValidation/ \"Download Primitively.FluentValidation from NuGet.org\") | FluentValidation support for Primitively types. |\n| `Primitively.MongoDB.Bson` | [![NuGet](https://buildstats.info/nuget/Primitively.MongoDB.Bson?includePreReleases=true)](https://www.nuget.org/packages/Primitively.MongoDB.Bson/ \"Download Primitively.MongoDB.Bson from NuGet.org\") | BSON serialization for Primitively types stored in MongoDB. |\n\n## Documentation\n\nThis README is designed to help you generate your own strongly typed identifiers with just a few lines of code.\n\nFor more detailed information about Primitively, check out [primitively.net][primitively-website].\n\n## Quick start\n\nTo get started, first add the [Primitively](https://www.nuget.org/packages/Primitively/) NuGet package to your project by running the following command:\n\n```sh\ndotnet add package Primitively\n```\n\nOpen your csproj file and edit the package reference, setting `PrivateAssets=\"All\"`. The file will look something like this afterwards:\n\n```XML\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n\n  \u003cPropertyGroup\u003e\n    \u003cTargetFramework\u003enet8.0\u003c/TargetFramework\u003e\n    \u003cImplicitUsings\u003eenable\u003c/ImplicitUsings\u003e\n    \u003cNullable\u003eenable\u003c/Nullable\u003e\n  \u003c/PropertyGroup\u003e\n\n  \u003cItemGroup\u003e\n    \u003cPackageReference Include=\"Primitively\" Version=\"1.4.21\" PrivateAssets=\"All\" /\u003e\n  \u003c/ItemGroup\u003e\n  \n\u003c/Project\u003e\n```\n\nYou are now ready to create your first Primitively source-generated type!\n\nCreate a new class file and add a reference to Primitively and decorate your `partial record struct` with one of the Primitively attributes such as `[Guid]`.\n\nFor example: -\n\n``` cs\nusing Primitively;\n\nnamespace Acme.Examples;\n\n[Guid]\npublic partial record struct ProductId;\n```\n\nHere's a list of all the Primitively attributes currently available: -\n\n- Date and time\n  - `[DateOnly]`\n- Globally unique identifiers\n  - `[Guid]`\n- Integers\n  - `[Byte]`\n  - `[Int]`\n  - `[Long]`\n  - `[SByte]`\n  - `[Short]`\n  - `[UInt]`\n  - `[ULong]`\n  - `[UShort]`\n- Floating-points (v1.5.x)\n  - `[Decimal]`\n  - `[Double]`\n  - `[Single]`\n- Strings\n  - `[String]`\n\nHere's some source generation in action using each of the above attributes: -\n\n![Primitively examples](docs/images/source-gen-anim-01.gif)\n\n## Using Primitively on an ASP.NET core web project\n\nIf you want to use your Primitively types in an ASP.NET core web project. Add the [Primitively.AspNetCore.Mvc](https://www.nuget.org/packages/Primitively.AspNetCore.Mvc/) NuGet package to your project by running the following command. It contains model binding support for your Primitively types, which means you can use your Primitively types in request parameters.\n\n```sh\ndotnet add package Primitively.AspNetCore.Mvc\n```\n\nIf you are also generating **swagger** documentation for a web API. Add the [Primitively.AspNetCore.SwaggerGen](https://www.nuget.org/packages/Primitively.AspNetCore.SwaggerGen/) NuGet package to your project by running the following command. \n\n```sh\ndotnet add package Primitively.AspNetCore.SwaggerGen\n```\n\nWhen using `FluentValidation` to validate your web requests. Add the [Primitively.FluentValidation](https://www.nuget.org/packages/Primitively.FluentValidation/) NuGet package to your project by running the following command. It contains two extension methods which validate any Primitively type with zero DI configuration.\n\n```sh\ndotnet add package Primitively.FluentValidation\n```\n\n### Dependency injection\n\nHere's an example of the DI setup for a C# ASP.NET web API project that references a class library containing Primitively source generated types and is generating **swagger** documentation.\n\n```cs\nvar builder = WebApplication.CreateBuilder(args);\nbuilder.Services.AddControllers();\nbuilder.Services.AddEndpointsApiExplorer();\nbuilder.Services.AddSwaggerGen();\n\n// Add primitively configuration\nbuilder.Services.AddPrimitively(options =\u003e\n{\n    // Register the location of source generated Primitively types within the application\n    // NB. No need to use reflection to scan assemblies! Each class library that contains source\n    // generated Primitively types also have a 'PrimitiveLibrary' static helper class. Metadata such\n    // as a type name, underlying data type, example value, min/max Length etc can then be obtained\n    // from the PrimitiveRepository instance within each class library\n    options.Register(Acme.Lib1.PrimitiveLibrary.Repository);\n})\n// Add AspNetCore MVC model binding support for Primitively types used in APIs.  This means strongly typed\n// Primitively types can easily be used as query string and route params too etc\n.AddMvc()\n// Add Swashbuckle Open Api Schema Filter so Primitively types are fully supported in the API Swagger documentation \n.AddSwaggerGen();\n```\n\n## Using Primitively with MongoDB\n\nIf you want to store your Primitively types in MongoDB they will need a BSON serializer. Add the [Primitively.MongoDB.Bson](https://www.nuget.org/packages/Primitively.MongoDB.Bson/) NuGet package to your project by running the following command. It contains highly configurable BSON serialization support for your Primitively types.\n\n```sh\ndotnet add package Primitively.MongoDB.Bson\n```\n\n### Dependency injection\n\nHere's an example of the DI setup for a .NET core application that uses both MongoDB and Primitively.\n\n``` cs\nvar services = new ServiceCollection();\n\n// Add primitively configuration\nservices.AddPrimitively(options =\u003e\n{\n    // Register the location of source generated Primitively types within the application\n    options.Register(Acme.Lib1.PrimitiveLibrary.Repository);\n})\n// Add MongoDB BsonSerializer configuration. This method also supports registering types individually. By default\n// it will register a BSON serializer for each Primitively type in the PrimitivelyOptions registry.\n// Any Primitively types that are IGuid primitives will be by default stored in Mongo as the default CSharpLegacy Base64\n// strings unless overridden using the Bson serializer options\n.AddBson();\n```\n\nYour MongoDB-related Primitively types can be registered in this way as well: -\n\n```cs\nservices.AddPrimitively()\n    .AddBson(builder =\u003e builder.Register(Acme.Lib1.PrimitiveLibrary.Repository));\n```\n\nOr you can just register individual types rather than an entire library: -\n\n```cs\nservices.AddPrimitively()\n    .AddBson(builder =\u003e builder.Register\u003cProductId\u003e());\n```\n\nEach Primitively type's BSON serializer can be configured individually. Here's an example of how to set the options for the BSON serializer used on all your Primitively `IGuid` types: -\n\n```cs\nservices.AddPrimitively()\n    .AddBson(builder =\u003e builder\n        .Register(Acme.Lib1.PrimitiveLibrary.Repository)\n        .Configure\u003cBsonIGuidSerializerOptions\u003e(options =\u003e options\n            .GuidRepresentation = MongoDB.Bson.GuidRepresentation.Standard));\n```\n\n## Next steps\n\nTo learn more about Primitively, go to [primitively.net][primitively-website].\n\n## Examples\n\nSample applications that demonstrate scenarios in which Primitively is commonly used are available for learning purposes in the *examples* folder.\n\n## Licence\n\nLicensed under the terms of the [MIT License](https://opensource.org/license/mit/)\n\n[primitively-website]: https://primitively.net\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdtanglr%2Fprimitively","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdtanglr%2Fprimitively","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdtanglr%2Fprimitively/lists"}