{"id":20607289,"url":"https://github.com/qjake/hadotnet","last_synced_at":"2025-04-05T19:14:41.739Z","repository":{"id":40909945,"uuid":"198331327","full_name":"qJake/HADotNet","owner":"qJake","description":"🏡 A .NET Standard library for Home Assistant.","archived":false,"fork":false,"pushed_at":"2022-12-08T09:06:24.000Z","size":106,"stargazers_count":92,"open_issues_count":7,"forks_count":21,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-05T19:14:27.310Z","etag":null,"topics":["api","home-assistant","home-automation","library"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qJake.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["qJake"]}},"created_at":"2019-07-23T01:52:36.000Z","updated_at":"2025-02-20T00:31:44.000Z","dependencies_parsed_at":"2023-01-24T20:25:11.553Z","dependency_job_id":null,"html_url":"https://github.com/qJake/HADotNet","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qJake%2FHADotNet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qJake%2FHADotNet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qJake%2FHADotNet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qJake%2FHADotNet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qJake","download_url":"https://codeload.github.com/qJake/HADotNet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247386266,"owners_count":20930619,"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","home-assistant","home-automation","library"],"created_at":"2024-11-16T10:06:17.460Z","updated_at":"2025-04-05T19:14:41.699Z","avatar_url":"https://github.com/qJake.png","language":"C#","funding_links":["https://github.com/sponsors/qJake","https://www.buymeacoffee.com/qJake"],"categories":[],"sub_categories":[],"readme":"# HADotNet\n\n[![Nuget](https://img.shields.io/nuget/v/HADotNet.Core?logo=nuget)](https://www.nuget.org/packages/HADotNet.Core/)\n![ci-badge](https://github.com/qJake/HADotNet/workflows/CI%20Build/badge.svg)\n\n[![Buy me a coffee](https://raw.githubusercontent.com/qJake/HADotNet.CommandCenter/master/Assets/bmac.png)](https://www.buymeacoffee.com/qJake)\n\nA simple, straighforward .NET Standard library for the [Home Assistant](https://github.com/home-assistant/home-assistant) API.\n\n## Features\n\n* .NET Standard 2.0 cross-platform library\n* DI-friendly client initialization (suitable for ASP.NET Core)\n* Home Assistant data is represented by strongly-typed, commented model classes\n\n### Supported Home Assistant APIs\n\n* Root API (*Verifies the HA API is responding*)\n* Automation API\n* Google Calendar API (*Unofficial*)\n* Discovery API\n* Config API\n* Camera Proxy API\n* Entity API\n* Error Log API\n* Events API\n* History API\n* Logbook API\n* Services API\n* States API\n* Supervisor API (Supervisor-based installations only)\n* Template API\n\n## Getting Started\n\n### From NuGet (Recommended)\n\n[![Nuget](https://img.shields.io/nuget/dt/HADotNet.Core?color=%23004880\u0026label=NuGet%20Downloads\u0026logo=nuget)](https://www.nuget.org/packages/HADotNet.Core/)\n\nInstall **[HADotNet.Core](https://www.nuget.org/packages/HADotNet.Core/)** from NuGet:\n\n`Install-Package HADotNet.Core`\n\n### From Source\n\nClone this repo and either include the `HADotNet.Core` library in your project, \nor build the project and include the DLL as a reference.\n\n## Examples\n\n### Initializing The Client Factory\n\nThe `ClientFactory` class is reponsible for initializing all other clients in a \nreusable way, so you only have to define your instance URL and API key once.\n\nTo initialize the `ClientFactory`, pass in your base Home Assistant URL and a\nlong-lived access token that you created on your profile page.\n\n```csharp\nClientFactory.Initialize(\"https://my-home-assistant-url/\", \"AbCdEf0123456789...\");\n```\n\n### Integrating into an ASP.NET Core Site\n\nFirst, call `ClientFactory.Initialize(...);` to ensure that your Home Assistant\ninstance is connected. You can do this in `ConfigureServices`, or using middleware.\n\nJust be sure that the client factory has been initialized **before** any page/controller\nrequests are made.\n\nYou can add individual clients to the DI container like so:\n\n```csharp\nservices.AddScoped(_ =\u003e ClientFactory.GetClient\u003cEntityClient\u003e());\nservices.AddScoped(_ =\u003e ClientFactory.GetClient\u003cStatesClient\u003e());\nservices.AddScoped(_ =\u003e ClientFactory.GetClient\u003cServiceClient\u003e());\nservices.AddScoped(_ =\u003e ClientFactory.GetClient\u003cDiscoveryClient\u003e());\n```\n\nSince there are no interfaces, simply add the instance(s) directly into the container.\nAdd as few or as many clients as you need, and then simply retrieve each client via the\nDI container as-needed.\n\n```csharp\npublic class MyController : Controller\n{\n\tprivate IOtherService SampleService { get; }\n\tprivate EntityClient EntityClient { get; }\n\n\tpublic MyController(IOtherService sampleService, EntityClient entityClient)\n\t{\n\t\tSampleService = sampleService;\n\t\tEntityClient = entityClient;\n\t}\n\n\t// ...\n}\n```\n\n### Getting Home Assistant's Current Configuration\n\nGet a `ConfigClient` and then call `GetConfiguration()`:\n\n```csharp\nvar configClient = ClientFactory.GetClient\u003cConfigClient\u003e();\nvar config = await configClient.GetConfiguration();\n// config.LocationName: \"Home\"\n// config.Version: 0.96.1\n```\n\n### Retrieving All Entities\n\nGet an `EntityClient` and then call `GetEntities()`:\n\n```csharp\nvar entityClient = ClientFactory.GetClient\u003cEntityClient\u003e();\nvar entityList = await entityClient.GetEntities();\n```\n\n### Retrieving Entities By Domain\n\nGet an `EntityClient` and then call `GetEntities(\"domainName\")`:\n\n```csharp\nvar entityClient = ClientFactory.GetClient\u003cEntityClient\u003e();\nvar filteredEntityList = await entityClient.GetEntities(\"light\");\n```\n\n### Retrieving All Entity States\n\nGet a `StatesClient` and then call `GetStates()`:\n\n```csharp\nvar statesClient = ClientFactory.GetClient\u003cStatesClient\u003e();\nvar allMyStates = await statesClient.GetStates();\n```\n\n### Retrieving State By Entity\n\nGet a `StatesClient` and then call `GetState(entity)`:\n\n```csharp\nvar statesClient = ClientFactory.GetClient\u003cStatesClient\u003e();\nvar state = await statesClient.GetState(\"sun.sun\");\n// state.EntityId: \"sun.sun\"\n// state.State: \"below_horizon\"\n```\n\n### Retrieving All Service Definitions\n\nGet a `ServiceClient` and then call `GetServices()`:\n\n```csharp\nvar serviceClient = ClientFactory.GetClient\u003cServiceClient\u003e();\nvar services = await serviceClient.GetServices();\n```\n\n### Retrieving Calendar Events\n\nGet a `CalendarClient` and then call `GetEvents(calEntity)`:\n\n```csharp\nvar calClient = ClientFactory.GetClient\u003cCalendarClient\u003e();\nvar myEvents = await calClient.GetEvents(\"calendar.my_calendar\");\n```\n\n### Calling a Service\n\nGet a `ServiceClient` and then call `CallService()`:\n\n```csharp\nvar serviceClient = ClientFactory.GetClient\u003cServiceClient\u003e();\n\nvar resultingState = await serviceClient.CallService(\"homeassistant\", \"restart\");\n// Or\nvar resultingState = await serviceClient.CallService(\"light\", \"turn_on\", new { entity_id = \"light.my_light\" });\n// Or\nvar resultingState = await serviceClient.CallService(\"light.turn_on\", new { entity_id = \"light.my_light\" });\n// Or\nvar resultingState = await serviceClient.CallService(\"light.turn_on\", @\"{\"\"entity_id\"\":\"\"light.my_light\"\"}\");\n```\n\n### Retrieving History for an Entity\n\nGet a `HistoryClient` and then call `GetHistory(entityId)`:\n\n```csharp\nvar historyClient = ClientFactory.GetClient\u003cHistoryClient\u003e();\nvar historyList = await historyClient.GetHistory(\"sun.sun\");\n\n// historyList.EntityId: \"sun.sun\"\n// historyList[0].State: \"above_horizon\"\n// historyList[0].LastUpdated: 2019-07-25 07:25:00\n// historyList[1].State: \"below_horizon\"\n// historyList[1].LastUpdated: 2019-07-25 20:06:00\n```\n\n### Rendering a Template\n\nGet a `TemplateClient` and then call `RenderTemplate(templateBody)`:\n\n```csharp\nvar templateClient = ClientFactory.GetClient\u003cTemplateClient\u003e();\nvar myRenderedTemplate = await templateClient.RenderTemplate(\"The sun is {{ states('sun.sun') }}\");\n\n// myRenderedTemplate: The sun is above_horizon\n```\n\n### Retrieving a Camera Image\n\nGet a `CameraProxyClient` and then call `GetCameraImage`, or for a ready-to-go HTML Base64 string, `GetCameraImageAsBase64`:\n\n```csharp\nvar cameraClient = ClientFactory.GetClient\u003cCameraProxyClient\u003e();\nvar myCameraImage = await cameraClient.GetCameraImageAsBase64(\"camera.my_camera\");\n\n// myCameraImage: \"data:image/jpg;base64,AAAAAAAAA...\"\n```\n\n## Testing\n\nTo run the unit tests, you must first set two environment variables:\n\n* `HADotNet:Tests:Instance` = `https://my-home-assistant-url/`\n* `HADotNet:Tests:ApiKey` = `AbCdEf0123456789...`\n\n## Collaborating\n\nFork the project, make some changes, and submit a pull request!\n\nBe sure to follow the same coding style (generally, the standard Microsoft C# coding \nguidelines) and comment all publicly-visible types and members with XMLDoc comments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqjake%2Fhadotnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqjake%2Fhadotnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqjake%2Fhadotnet/lists"}