Update one record

Runs the sample. Generated for this page; it reads the connection string from the environment and first remakes the sample database from sample-schema.json.

using ArxSamples.MongoDb;
using ArxSamples.MongoDb.Operations.Update.Basics;

// The connection string comes from the environment, never from the code (see "Configure the connection").
var connectionString = Environment.GetEnvironmentVariable("ARX_SAMPLES_MONGODB")
    ?? throw new InvalidOperationException("Set the ARX_SAMPLES_MONGODB environment variable to your MongoDB connection string.");

var dbContext = new SampleContext(connectionString);

// Every run starts from the sample data: this deletes and makes again what sample-schema.json lists
// (save the file in the project folder, see Get started).
await dbContext.Direct.ResetAsync();

await new Basic1_UpdateOneRecord().RunAsync(dbContext);

The sample, as it is in the repository.

using ARX.SDK;
using ARX.SDK.MongoDb.Services;
using ARX.SDK.Services;

using static ArxSamples.MongoDb.SampleOutput;

namespace ArxSamples.MongoDb.Operations.Update.Basics;

/// <summary>
/// The smallest update, in three scenarios: by the id Create returned, clearing a value, and a record that isn't there.
/// </summary>
/// <remarks>
/// Only the attributes you set are written (<c>$set</c>); a field left out keeps its value; an attribute set to null is
/// stored as null. Nothing matched is ARX2002. A document's <c>_id</c> can't change in MongoDB.
/// </remarks>
public sealed class Basic1_UpdateOneRecord : ISample
{
    public string Name => "update-basics-1-update-one-record";

    public string Title => "Update one record";

    public async Task RunAsync(SampleContext dbContext)
    {
        var account = new ArxEntity("account");
        account["name"] = "Fourth Coffee";
        account["account_number"] = "ACC-M801";
        account["employee_count"] = 40;
        account["website"] = "https://fourthcoffee.example";
        var id = await dbContext.Service.CreateAsync(account);

        await Scenario1_ByTheIdCreateReturnedAsync(dbContext.Service, id);

        await Scenario2_ClearAValueAsync(dbContext.Service, id);

        await Scenario3_ARecordThatIsntThereAsync(dbContext.Service);
    }

    /// <summary>1. Give the entity the id CreateAsync returned, and only the fields to change.</summary>
    private static async Task Scenario1_ByTheIdCreateReturnedAsync(ArxMongoDbService service, ArxRecordId id)
    {
        Step("1. By the id Create returned");

        var change = new ArxEntity("account") { RecordId = id };
        change["employee_count"] = 55;

        int changed = await service.UpdateAsync(change);

        Show($"{changed} document changed");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.account.find({ account_number: "ACC-M801" }, { name: 1, employee_count: 1 })
         * -- Expect: 1 document, Fourth Coffee, employee_count 55.
         * ===========================================================
         */
    }

    /// <summary>2. Null stores null: the field stays, empty.</summary>
    private static async Task Scenario2_ClearAValueAsync(ArxMongoDbService service, ArxRecordId id)
    {
        Step("2. Clear a value");

        var change = new ArxEntity("account") { RecordId = id };
        change["website"] = null;

        await service.UpdateAsync(change);

        Show("website cleared");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.account.find({ account_number: "ACC-M801" }, { website: 1 })
         * -- Expect: 1 document, website null.
         * ===========================================================
         */
    }

    /// <summary>3. An id no document has: ARX2002.</summary>
    private static async Task Scenario3_ARecordThatIsntThereAsync(ArxMongoDbService service)
    {
        Step("3. A record that isn't there");

        var change = new ArxEntity("account") { RecordId = ArxRecordId.Of("account_id", "64b7f0c2a1b2c3d4e5f60718") };
        change["employee_count"] = 1;

        try
        {
            await service.UpdateAsync(change);
        }
        catch (ArxException exception) when (exception.Code == ArxErrorCode.RecordNotFound)
        {
            ShowError(exception);
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.account.countDocuments({ _id: ObjectId("64b7f0c2a1b2c3d4e5f60718") })
         * -- Expect: 0.
         * ===========================================================
         */
    }
}

  > 1. By the id Create returned
      1 document changed
  > 2. Clear a value
      website cleared
  > 3. A record that isn't there
      caught ArxException: ARX2002 RecordNotFound: Update of 'account': no document matched the entity's id (field account_id).