Hello World: Minimal Modern Adapter¶

Goal: Build the smallest valid modern adapter shape.

What you'll learn:

minimal project structure
minimal adapter-registration.yaml
root Thing with immediate connection
source-generated startup shape

Time: ~10 minutes

Step 1: Create Project¶

mkdir Pq.Adapter.Hello

Step 2: Create Project File¶

Create Pq.Adapter.Hello.csproj:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
    <CompilerGeneratedFilesOutputPath>.\.GeneratedFiles</CompilerGeneratedFilesOutputPath>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" />
    <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\..\Pq.Adapters.Framework\Pq.Adapters.Framework.csproj" />
    <ProjectReference Include="..\..\Pq.Domain\Pq.Domain.csproj" />
    <ProjectReference Include="..\..\Pq.Adapters.Framework.SourceGenerator\Pq.Adapters.Framework.SourceGenerator.csproj"
                      OutputItemType="Analyzer"
                      ReferenceOutputAssembly="false" />
  </ItemGroup>

  <ItemGroup>
    <AdditionalFiles Include="adapter-registration.yaml" />
  </ItemGroup>
</Project>

Step 3: Create Minimal YAML¶

Create adapter-registration.yaml:

adapter_id: "00000000-0000-0000-0000-000000000001"
name: "Hello World Adapter"
version: "1.0.0"
manufacturer: "PQ"
description: "Minimal modern adapter"
adapter_type: "security"
security_domains: ["access"]

capabilities:
  auto_discovery: false
  time_sync: false
  firmware_update: false
  config_backup: false

transport:
  type: custom
  protocol:
    type: "None"

device_types:
  - type_id: "TestDevice"
    name: "Test Device"
    description: "Minimal root device"
    commands:
    functions:

Step 4: Create Root Thing¶

Create Devices/TestDevice.cs:

using Pq.Adapters.Framework.Communication;

namespace Pq.Adapter.Hello;

public partial class TestDevice : IDeviceConnection
{
    public Task<bool> Connect(ConnectionContext context, CancellationToken ct)
        => Task.FromResult(true);

    public Task Disconnect(CancellationToken ct)
        => Task.CompletedTask;
}

Step 5: Build¶

dotnet build

After the first build you should see generated files under .GeneratedFiles/.

Step 6: Verify Shape¶

Check that:

the project builds
.GeneratedFiles/ contains generated startup and Thing code
no handwritten Program.cs is required

What Just Happened?¶

The framework loaded adapter-registration.yaml.
The source generator produced startup and Thing infrastructure.
Your root Thing provides the minimal connection lifecycle.

Next Steps¶

Read ../examples/minimal-generated-adapter.md to add one command path.
Read ../archetypes/ to choose the right shape if you need real communication.
Continue with 01-yaml-configuration.md for a fuller YAML model.