From 4b61c3742bfa9b61081e7001bffe259e1979009d Mon Sep 17 00:00:00 2001 From: Shun Kayaki Date: Sun, 14 Sep 2025 14:32:47 +0900 Subject: [PATCH] fix(docs): correct OSCQueryServiceBuilder.WithDefaults() usage - Update README.md Basic Use section with correct example - Fix getting-started.md fluent interface examples - Add warnings about WithDefaults() immediate server startup - Clarify that settings must be configured before WithDefaults() --- Readme.md | 12 +++++++++++- getting-started.md | 8 +++++--- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/Readme.md b/Readme.md index 19d6743..188428f 100644 --- a/Readme.md +++ b/Readme.md @@ -22,7 +22,17 @@ This library does not yet return limited attributes based on query strings, like ## ⚡️ Basic Use 1. Build vrc-oscquery-lib into vrc-oscquery-lib.dll and add it to your project (will make this a NuGet package once it's ready for wider use). -2. Construct a new OSCQuery service with `new OSCQueryServiceBuilder().WithDefaults().Build()`. T optionally passing in the name, TCP port to use for serving HTTP, UDP port that you're using for OSC, and an ILogger if you want logs. +2. Construct a new OSCQuery service. + - **Important**: If you want to customize settings (name, ports, etc.), configure them **before** calling `WithDefaults()`, as `WithDefaults()` immediately starts the HTTP server and advertising. + ```csharp + var service = new OSCQueryServiceBuilder() + .WithTcpPort(Extensions.GetAvailableTcpPort()) + .WithUdpPort(Extensions.GetAvailableUdpPort()) + .WithServiceName("MyService") + .WithDefaults() + .Build(); + ``` + 3. You should now be able to visit `http://localhost:tcpPort` in a browser and see raw JSON describing an empty root node. - You can also visit `http://localhost:tcpPort?explorer` to see an OSCQuery Explorer UI for the OSCQuery service, which should be easier to navigate than the raw JSON. 4. You can also visit `http://localhost:tcpPort?HOST_INFO` to get information about the supported attributes of this OSCQuery Server. diff --git a/getting-started.md b/getting-started.md index 597fbb7..f249265 100644 --- a/getting-started.md +++ b/getting-started.md @@ -27,6 +27,7 @@ The format is always `new OSCQueryServiceBuilder()`, followed by all the things There's a lot of options you _can_ configure if you want more control over what happens. The additional methods are listed below. Note that if you do not add any fluent options, then `WithDefaults()` is called for you automatically. * WithDefaults() + * **Important**: This immediately starts the HTTP server and advertising. Configure all settings (ports, names, etc.) **before** calling this method. * Sets up Discovery, Advertising and HTTP serving using default names and ports. * WithTcpPort(int port) * Set the TCP port you want to use for serving the HTTP endpoints. Defaults to any available open TCP port. @@ -53,15 +54,16 @@ There's a lot of options you _can_ configure if you want more control over what * AddListenerForServiceType(Action\ listener, OSCQueryServiceProfile.ServiceType type) * Adds a listener which will be sent OSCQueryServiceProfiles for newly-discovered OSC or OSCQuery services. -You can can add these onto `.WithDefaults()` if you want _almost_ all the defaults. For example, this code will have all the defaults, but find the first available TCP port instead of 8060, and uses the name "MyService" instead of "OSCQueryService". +**Important**: You must configure settings **before** calling `.WithDefaults()`, as `WithDefaults()` immediately starts the HTTP server and advertising. Settings configured after `WithDefaults()` will not be applied. ```csharp var oscQuery = new OSCQueryServiceBuilder() - .WithDefaults() .WithTcpPort(Extensions.GetAvailableTcpPort()) .WithServiceName("MyService") + .WithDefaults() .Build(); ``` + ## A Simple Example A minimal example for a working OSCQuery Service could look like this: @@ -71,10 +73,10 @@ var tcpPort = Extensions.GetAvailableTcpPort(); var udpPort = Extensions.GetAvailableUdpPort(); var oscQuery = new OSCQueryServiceBuilder() - .WithDefaults() .WithTcpPort(tcpPort) .WithUdpPort(udpPort) .WithServiceName("MyService") + .WithDefaults() // Configure settings BEFORE calling WithDefaults() .Build(); // Manually logging the ports to see them without a logger