{"id":26611254,"url":"https://github.com/hexarc-software/hexarc-pact","last_synced_at":"2025-10-15T04:28:02.257Z","repository":{"id":57115806,"uuid":"337060308","full_name":"hexarc-software/hexarc-pact","owner":"hexarc-software","description":"Hassle-free API integrations for .NET web services. Batteries included.","archived":false,"fork":false,"pushed_at":"2022-12-11T10:03:37.000Z","size":409,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-10T00:52:25.170Z","etag":null,"topics":["api","aspnet","discovery","dotnet","http","integration","json","pact","protocol","schema","typescript","webapi"],"latest_commit_sha":null,"homepage":"","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/hexarc-software.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-08T11:54:32.000Z","updated_at":"2024-04-17T12:05:45.000Z","dependencies_parsed_at":"2023-01-26T20:46:25.114Z","dependency_job_id":null,"html_url":"https://github.com/hexarc-software/hexarc-pact","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexarc-software%2Fhexarc-pact","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexarc-software%2Fhexarc-pact/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexarc-software%2Fhexarc-pact/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexarc-software%2Fhexarc-pact/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hexarc-software","download_url":"https://codeload.github.com/hexarc-software/hexarc-pact/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137995,"owners_count":21053775,"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":["api","aspnet","discovery","dotnet","http","integration","json","pact","protocol","schema","typescript","webapi"],"created_at":"2025-03-24T02:35:25.369Z","updated_at":"2025-10-15T04:27:57.199Z","avatar_url":"https://github.com/hexarc-software.png","language":"C#","readme":"# Hexarc Pact\nHexarc Pact provides a toolchain for exposing and consuming Web API for .NET/TypeScript-based projects.\n\nDevelop your .NET Web API project with Pact to keep a single source of truth for the API metadata and consume it across the .NET ecosystem \n(microservices, desktop and mobile applications) or on the Web via TypeScript.\n\n|Package| Platform   |Version|Downloads|\n|-------|------------|-------|---------|\n|`Hexarch.Pact.Protocol`| .NET 7.0+  | [![Version](https://img.shields.io/nuget/v/Hexarc.Pact.Protocol.svg)](https://nuget.org/packages/Hexarc.Pact.Protocol) | [![Downloads](https://img.shields.io/nuget/dt/Hexarc.Pact.Protocol.svg)](https://nuget.org/packages/Hexarc.Pact.Protocol) |\n|`Hexarch.Pact.AspNetCore`| .NET 7.0+  | [![Version](http://img.shields.io/nuget/v/Hexarc.Pact.AspNetCore.svg)](https://nuget.org/packages/Hexarc.Pact.AspNetCore) | [![Downloads](https://img.shields.io/nuget/dt/Hexarc.Pact.AspNetCore.svg)](https://nuget.org/packages/Hexarc.Pact.AspNetCore) |\n|`Hexarch.Pact.Client`| .NET 7.0+  | [![Version](http://img.shields.io/nuget/v/Hexarc.Pact.Client.svg)](https://nuget.org/packages/Hexarc.Pact.Client) | [![Downloads](https://img.shields.io/nuget/dt/Hexarc.Pact.Client.svg)](https://nuget.org/packages/Hexarc.Pact.Client) |\n|`Hexarch.Pact.Tool`| .NET 7.0+  | [![Version](http://img.shields.io/nuget/v/Hexarc.Pact.Tool.svg)](https://nuget.org/packages/Hexarc.Pact.Tool) | [![Downloads](https://img.shields.io/nuget/dt/Hexarc.Pact.Tool.svg)](https://nuget.org/packages/Hexarc.Pact.Tool) |\n|`@hexarc/pact-tool`| TypeScript | [![Version](http://img.shields.io/npm/v/@hexarc/pact-tool.svg)](https://www.npmjs.org/package/@hexarc/pact-tool) | [![Downloads](http://img.shields.io/npm/dt/@hexarc/pact-tool.svg)](https://www.npmjs.org/package/@hexarc/pact-tool) |\n\n## What's in Pact?\n* [Features](#features)\n* [Type system](#type-system)\n* [API annotation rules](#api-annotation-rules)\n  * [Additional attributes](#additional-attributes)\n* [Demo API](#demo-api-server)\n* [How to use](#how-to-use)\n  * [Expose Pact API schema](#expose-pact-api-schema) (.NET Web API service)\n  * [Consume Pact API schema](#consume-pact-api-schema) (.NET client application)\n* [Acknowledgments](#acknowledgments) \n* [License](#license)\n\n## Features\n* Hassle-free API integrations in seconds.\n* No type information loosing. Consume exact API as it's designed.\n* Code first. No need to describe your API protocol in external IDL/DSL.\n* Charged with advanced types. Not only simple DTOs but enums, generics, tagged unions, etc.\n\n## Type system\nThe Pact type system is based on the .NET CLR types with some bespoke ones\nfor the best development experience. \n\nWhat's inside the Pact type system:\n* Primitive types (including `Guid` and `DateTime`)\n* Value/Reference type semantics\n* Collections and generics (not only simple arrays and dictionaries)\n* Complete support for Nullable Reference Type annotations (NRT)\n* Enums (string-based and number-based)\n* Tagged Unions (via [Hexarc.Serialization.Union](https://github.com/hexarc-software/hexarc-serialization))\n* Tuples (via [Hexarc.Serialization.Tuple](https://github.com/hexarc-software/hexarc-serialization))\n\n## API annotation rules\nThe Pact API schema is designed to have an RPC-like semantic. In doing so \nan exposed API must follow these rules:\n* API controllers must be marked with standard `ApiController` and `Route` attributes.\n* Route attribute must have only a constant string path without templating (e.g. `[Route(\"Entities\")]`).\n* API methods must be marked with one of the supported HTTP verbs (`HttpGet` or `HttpPost`). Verb attributes may contain an endpoint path. \n  Others are not supported at the moment. \n   * `HttpGet` methods can have query parameters which must be bind via the `FromQuery` attribute.\n   * `HttpPost` methods must have only one parameter which is the request body.\n* API method path can be specified in the HTTP verb attribute or the `Route` attribute. If the method path is not\nspecified in the HTTP verb attribute it will be taken from the `Route` one or an exception will be raised.\n\n### Additional attributes\nPact provides some useful attributes for API annotation:\n* `PactIgnoreAttribute` can be applied to API controllers or methods to be excluded from an API schema.\n* `PactScopeAttribute` can be applied to API controllers to be isolated into specific scope in an API schema.\n\n## Demo API server\nDemo API server can be found at https://hexarc-demo-api.herokuapp.com/.\n\nThe Pact API schema is exposed at https://hexarc-demo-api.herokuapp.com/pact/schema.\n\nTo generate an API client use the [instruction](#consume-pact-api-schema)\nbelow.\n\n## How to use\nFind out how to use Pact to expose and consume a typical Web API.\n\n### Expose Pact API schema\n1. Install the `Hexarc.Pact.AspNetCore` package in a .NET Web API project:\n```shell\ndotnet add package Hexarc.Pact.AspNetCore\n```\n2. Add the Pact schema generation in the `Startup.ConfigureServices` method:\n```c#\npublic void ConfigureServices(IServiceCollection services)\n{\n    services.AddControllers();\n\n    // Register the Pact schema generation.\n    services.AddPactGeneration();\n}\n```\n3. Enable the Pact middleware in the `Startup.Configure` method:\n```c#\npublic void Configure(IApplicationBuilder app)\n{\n    // Enable the Pact middleware to expose the generated API schema.\n    app.UsePact();\n\n    app.UseRouting();\n    app.UseEndpoints(endpoints =\u003e endpoints.MapControllers());\n}\n```\n4. Implement an API controller according to the Pact annotation rules:\n```c#\n[ApiController, Route(\"Misc\")]\npublic sealed class MiscController : ControllerBase\n{\n    [HttpGet(nameof(Ping))]\n    public String Ping([FromQuery] String message) =\u003e $\"Hello, {message}\";\n}\n```\n5. Start the app and open the `YOUR_API_HOST/pact/schema` address to ensure \n   the Pact API schema is generated.\n   \n### Consume Pact API schema\n1. Install the `Hexarc.Pact.Client` package in a .NET project:\n```shell\ndotnet add package Hexarc.Pact.Client\n```\n2. Install the `Hexarc.Pact.Tool` tool in the project:\n```shell\ndotnet tool install Hexarc.Pact.Tool\n```\nYou may need to setup a .NET tools manifesto before \ninstall the `Hexarc.Pact.Tool` tool:\n```shell\ndotnet new tool-manifest\n```\n3. Add a `pact.json` config in the project with a desired API client \n   generation settings:\n```json\n{\n   \"schemaUri\": \"YOUR_API_HOST/pact/schema\",\n   \"clientClassName\": \"DemoClient\",\n   \"clientClassNamespace\": \"DemoNamespace\",\n   \"outputDirectory\": \"Generated\"\n}\n```\nwhere\n* `schemaUri` - link to a Pact API schema\n* `clientClassName` - name for a generated API client class\n* `clientClassNamespace` - namespace where to put in the generated API client class\n* `outputDirectory` - output directory for the generated sources\n4. Generate the API client via the Pact CLI tool:\n```shell\ndotnet pact\n```\nThis command must be performed in the same folder with the `pact.json` config.\n\n5. The generated API client will be available for accessing the API server:\n```c#\nvar client = new DemoClient(new HttpClient { BaseAddress = new Uri(\"YOUR_API_HOST\") });\nvar pong = await client.Misc.Ping(\"World\");\nConsole.WriteLine(pong); // Prints \"Hello, World\" to the output.\n```\n\n## Acknowledgments\nBuilt with JetBrains tools for [Open Source](https://jb.gg/OpenSourceSupport) projects. \n\n![JetBrains Logo (Main) logo](https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.svg)\n\n## License\nMIT © [Max Koverdyaev](https://github.com/shadeglare)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexarc-software%2Fhexarc-pact","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexarc-software%2Fhexarc-pact","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexarc-software%2Fhexarc-pact/lists"}