chore: readme updates and additions

README.template.md

@@ -4,14 +4,11 @@
 
 ### Requirements
 
-- You will most likely want an IDE that supports .NET development, such as [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs),
-  [JetBrains Rider](https://www.jetbrains.com/rider/), or [Microsoft Visual Studio Code](https://code.visualstudio.com/).
-- You will need the [`dotnet` runtime and command line tools](https://dotnet.microsoft.com/en-us/download).  After installing them,
-  you should have the `dotnet` command on your PATH.
+You will need the [`dotnet` runtime and command line tools](https://dotnet.microsoft.com/en-us/download).  After installing them, you should have the `dotnet` command on your PATH.
 
-### Installation
+**IDE Notes**: You will most likely want an IDE that supports .NET development, such as [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs), [JetBrains Rider](https://www.jetbrains.com/rider/), or [Microsoft Visual Studio Code](https://code.visualstudio.com/).
 
-If you'd like to see a complete working example, check out our [examples](./examples/README.md) page.
+### Installation
 
 To create a new .NET project and add the Momento client library as a dependency:
 
@@ -35,6 +32,26 @@ Here is a quickstart you can use in your own project:
 Note that the above code requires an environment variable named MOMENTO_AUTH_TOKEN which must
 be set to a valid [Momento authentication token](https://docs.momentohq.com/docs/getting-started#obtain-an-auth-token).
 
+**Momento Response Types**: The Momento `SimpleCacheClient` uses response types in a way you may not be familiar with and deserves
+a word of explanation upfront. Each response object's actual type will be a subtype (e.g., `CacheGetResponse.Hit`) of the requested response type (e.g., `CacheGetResponse`) and must be resolved to the correct subtype before accessing its properties. We recommend using [pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching) to resolve the response's subtype and allow us to access the appropriate properties for that type:
+
+```csharp
+CreateCacheResponse createResponse = client.CreateCacheAsync("example-cache");
+if (createResponse is CreateCacheResponse.CacheAlreadyExists)
+{
+      // this may or may not be expected; handle as appropriate.
+}
+else if (createResponse is CreateCacheResponse.Error createError)
+{
+      if (createError.ErrorCode == MomentoErrorCode.LIMIT_EXCEEDED_ERROR)
+      {
+            // we've used our quota of caches; we should contact [email protected]!
+      }
+}
+```
+
+See the "Error Handling" section below for more details.
+
 ### Error Handling
 
 Error that occur in calls to SimpleCacheClient methods are surfaced to developers as part of the return values of

examples/MomentoApplication/README.md

@@ -0,0 +1,72 @@
+<img src="https://docs.momentohq.com/img/logo.svg" alt="logo" width="400"/>
+
+# Momento Application Example
+
+This example is intended to show off the complete suite of Momento's cache client's
+functionality, including:
+
+* instantiating the Momento client
+* creating, listing, and deleting caches
+* setting and retrieving values for cache keys
+* response processing and error handling
+
+## Prerequisites
+
+* [`dotnet`](https://dotnet.microsoft.com/en-us/download) 6.0 or higher is required
+* A Momento auth token is required.  You can generate one using the [Momento CLI](https://github.com/momentohq/momento-cli).
+
+## Running the application example
+
+Run the following from within the `examples` directory:
+
+```bash
+MOMENTO_AUTH_TOKEN=<YOUR AUTH TOKEN> dotnet run --project MomentoApplication
+```
+
+Within the `MomentoAppication` directory you can run:
+
+```bash
+MOMENTO_AUTH_TOKEN=<YOUR AUTH TOKEN> dotnet run
+```
+
+## Error Handling
+
+Errors that occur in calls to SimpleCacheClient methods are surfaced to developers as part of the return values of
+the calls, as opposed to by throwing exceptions.  This makes them more visible, and allows your IDE to be more
+helpful in ensuring that you've handled the ones you care about.  (For more on our philosophy about this, see our
+blog post on why [Exceptions are bugs](https://www.gomomento.com/blog/exceptions-are-bugs).  And send us any
+feedback you have!)
+
+The preferred way of interpreting the return values from SimpleCacheClient methods is using [Pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching).  Here's a quick example:
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Hit hitResponse)
+{
+    Console.WriteLine($"\nLooked up value: {hitResponse.String()}, Stored value: {VALUE}");
+} else {
+      // you can handle other cases via pattern matching in `else if` blocks, or a default case
+      // via the `else` block.  For each return value your IDE should be able to give you code
+      // completion indicating the other possible types; in this case, `CacheGetResponse.Miss` and
+      // `CacheGetResponse.Error`.
+}
+```
+
+Using this approach, you get a type-safe `hitResponse` object in the case of a cache hit.  But if the cache read
+results in a Miss or an error, you'll also get a type-safe object that you can use to get more info about what happened.
+
+In cases where you get an error response, `Error` types will always include an `ErrorCode` that you can use to check
+the error type:
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Error errorResponse)
+{
+    if (errorResponse.ErrorCode == MomentoErrorCode.TIMEOUT_ERROR) {
+       // this would represent a client-side timeout, and you could fall back to your original data source
+    }
+}
+```
+
+Note that, outside of SimpleCacheClient responses, exceptions can occur and should be handled as usual. For example, trying to instantiate a SimpleCacheClient with an invalid authentication token will result in an
+IllegalArgumentException being thrown.

examples/MomentoLoadGen/README.md

@@ -0,0 +1,42 @@
+<img src="https://docs.momentohq.com/img/logo.svg" alt="logo" width="400"/>
+
+# Momento Load Generator Example
+
+This repo includes a very basic load generator, to allow you to experiment with performance in your environment based on
+different configurations. It's very simplistic, and only intended to give you a quick way to explore the performance of
+the Momento client running in a single C# process.
+
+You can find the code in [Program.cs](./Program.cs).  At the bottom of the file are several
+configuration options you can tune.  For example, you can experiment with the number of concurrent requests; increasing
+this value will often increase throughput, but may impact client-side latency.  Likewise, decreasing the number of
+concurrent requests may increase client-side latency if it means less competition for resources on the machine your
+client is running on.
+
+Performance will be impacted by network latency, so you'll get the best results if you run on a cloud VM in the same
+region as your Momento cache.  The Momento client libraries ship with pre-built configurations that are tuned for
+performance in different environments; look for the `IConfiguration` at the bottom of the loadgen code.  You may wish to
+change that value from `Configurations.Laptop` to `Configurations.InRegion` if you will be running your client code
+on a cloud VM.
+
+If you have questions or need help experimenting further, please reach out to us at `[email protected]`!
+
+## Prerequisites
+
+* [`dotnet`](https://dotnet.microsoft.com/en-us/download) 6.0 or higher is required
+* A Momento auth token is required.  You can generate one using the [Momento CLI](https://github.com/momentohq/momento-cli).
+
+## Running the load generator
+
+To run the load generator (from the `examples` directory):
+
+```bash
+# Run example load generator
+MOMENTO_AUTH_TOKEN=<YOUR AUTH TOKEN> dotnet run --project MomentoLoadGen
+```
+
+Within the `MomentoLoadGen` directory you can run:
+
+```bash
+# Run example load generator
+MOMENTO_AUTH_TOKEN=<YOUR AUTH TOKEN> dotnet run
+```

examples/MomentoUsage/README.md

@@ -0,0 +1,68 @@
+<img src="https://docs.momentohq.com/img/logo.svg" alt="logo" width="400"/>
+
+# Momento Usage Example
+
+This example is intended to provide a quick glimpse at a minimal set of the Momento
+cache client's functionality. For a more extensive example that shows off
+the client's full capabilities, take a look at the more advanced  [MomentoApplication example](https://github.com/momentohq/client-sdk-dotnet/blob/main/examples/MomentoApplication/).
+
+## Prerequisites
+
+* [`dotnet`](https://dotnet.microsoft.com/en-us/download) 6.0 or higher is required
+* A Momento auth token is required.  You can generate one using the [Momento CLI](https://github.com/momentohq/momento-cli).
+
+## Running the application example
+
+Run the following from within the `examples` directory:
+
+```bash
+MOMENTO_AUTH_TOKEN=<YOUR AUTH TOKEN> dotnet run --project MomentoUsage
+```
+
+Within the `MomentoUsage` directory you can run:
+
+```bash
+MOMENTO_AUTH_TOKEN=<YOUR AUTH TOKEN> dotnet run
+```
+
+## Error Handling
+
+Errors that occur in calls to SimpleCacheClient methods are surfaced to developers as part of the return values of
+the calls, as opposed to by throwing exceptions.  This makes them more visible, and allows your IDE to be more
+helpful in ensuring that you've handled the ones you care about.  (For more on our philosophy about this, see our
+blog post on why [Exceptions are bugs](https://www.gomomento.com/blog/exceptions-are-bugs).  And send us any
+feedback you have!)
+
+The preferred way of interpreting the return values from SimpleCacheClient methods is using [Pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching).  Here's a quick example:
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Hit hitResponse)
+{
+    Console.WriteLine($"\nLooked up value: {hitResponse.ValueString}, Stored value: {VALUE}");
+} else {
+      // you can handle other cases via pattern matching in `else if` blocks, or a default case
+      // via the `else` block.  For each return value your IDE should be able to give you code
+      // completion indicating the other possible types; in this case, `CacheGetResponse.Miss` and
+      // `CacheGetResponse.Error`.
+}
+```
+
+Using this approach, you get a type-safe `hitResponse` object in the case of a cache hit.  But if the cache read
+results in a Miss or an error, you'll also get a type-safe object that you can use to get more info about what happened.
+
+In cases where you get an error response, `Error` types will always include an `ErrorCode` that you can use to check
+the error type:
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Error errorResponse)
+{
+    if (errorResponse.ErrorCode == MomentoErrorCode.TIMEOUT_ERROR) {
+       // this would represent a client-side timeout, and you could fall back to your original data source
+    }
+}
+```
+
+Note that, outside of SimpleCacheClient responses, exceptions can occur and should be handled as usual. For example, trying to instantiate a SimpleCacheClient with an invalid authentication token will result in an
+IllegalArgumentException being thrown.

examples/README.md

@@ -4,12 +4,12 @@
 
 ## Prerequisites
 
-* `dotnet` 6.0 or higher is required
+* [`dotnet`](https://dotnet.microsoft.com/en-us/download) 6.0 or higher is required
 * A Momento auth token is required.  You can generate one using the [Momento CLI](https://github.com/momentohq/momento-cli).
 
-## Running the basic example
+## Running the advanced example
 
-To run the basic example code defined in [`MomentoApplication/Program.cs`](./MomentoApplication/Program.cs),
+To run the advanced example code defined in [`MomentoApplication/Program.cs`](./MomentoApplication/Program.cs),
 run the following from within the `examples` directory:
 
 ```bash
@@ -18,7 +18,7 @@ MOMENTO_AUTH_TOKEN=<YOUR AUTH TOKEN> dotnet run --project MomentoApplication
 
 ## Error Handling
 
-Error that occur in calls to SimpleCacheClient methods are surfaced to developers as part of the return values of
+Errors that occur in calls to SimpleCacheClient methods are surfaced to developers as part of the return values of
 the calls, as opposed to by throwing exceptions.  This makes them more visible, and allows your IDE to be more
 helpful in ensuring that you've handled the ones you care about.  (For more on our philosophy about this, see our
 blog post on why [Exceptions are bugs](https://www.gomomento.com/blog/exceptions-are-bugs).  And send us any