Create a record that refers to another

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.Create.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 Basic2_CreateWithALookup().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.Create.Basics;

/// <summary>
/// A document that refers to another: a contact of an account, in two scenarios. The reference is an
/// <see cref="ArxEntityReference"/> made from the id CreateAsync returned; one to a collection the schema doesn't declare
/// is refused before anything is sent.
/// </summary>
/// <remarks>
/// MongoDB has no foreign keys: ARX checks the reference against the schema (the collection is declared, the id has its
/// type) and stores it as the referenced id is stored, an ObjectId here.
/// </remarks>
public sealed class Basic2_CreateWithALookup : ISample
{
    public string Name => "create-basics-2-create-with-a-lookup";

    public string Title => "Create a record that refers to another";

    public async Task RunAsync(SampleContext dbContext)
    {
        await Scenario1_AContactOfAnAccountAsync(dbContext.Service);

        await Scenario2_AnUndeclaredCollectionAsync(dbContext.Service);
    }

    /// <summary>1. Create the account, then a contact whose account_id refers to it.</summary>
    private static async Task Scenario1_AContactOfAnAccountAsync(ArxMongoDbService service)
    {
        Step("1. A contact of an account");

        var account = new ArxEntity("account");
        account["name"] = "Litware, Inc.";
        account["account_number"] = "ACC-M201";
        ArxRecordId accountId = await service.CreateAsync(account);

        var contact = new ArxEntity("contact");
        contact["first_name"] = "Ada";
        contact["last_name"] = "Lovelace";
        contact["email"] = "ada@litware.example";
        contact["account_id"] = new ArxEntityReference("account", accountId);

        ArxRecordId contactId = await service.CreateAsync(contact);

        Show($"created contact {contactId.AsString()} of account {accountId.AsString()}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.contact.find({ email: "ada@litware.example" })
         * -- Expect: 1 document, account_id an ObjectId equal to the account's _id.
         * ===========================================================
         */
    }

    /// <summary>2. A reference to a collection the schema doesn't declare: ARX1005, nothing sent.</summary>
    private static async Task Scenario2_AnUndeclaredCollectionAsync(ArxMongoDbService service)
    {
        Step("2. A collection the schema doesn't declare");

        var contact = new ArxEntity("contact");
        contact["email"] = "nobody@litware.example";
        contact["account_id"] = new ArxEntityReference("customer", "64b7f0c2a1b2c3d4e5f60718");

        try
        {
            await service.CreateAsync(contact);
        }
        catch (ArxValidationException exception) when (exception.Code == ArxErrorCode.InvalidLookup)
        {
            ShowError(exception);
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.contact.find({ email: "nobody@litware.example" })
         * -- Expect: no documents.
         * ===========================================================
         */
    }
}

  > 1. A contact of an account
      created contact 6af5339d4d3ca49045b87562 of account 6af5339d4d3ca49045b87561
  > 2. A collection the schema doesn't declare
      caught ArxValidationException: ARX1005 InvalidLookup: Lookup 'account_id' on 'contact' refers to table 'customer', which the schema doesn't declare.