Create one record and get its id

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 Basic1_CreateOneRecord().RunAsync(dbContext);

The sample, as it is in the repository.

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

using static ArxSamples.MongoDb.SampleOutput;

namespace ArxSamples.MongoDb.Operations.Create.Basics;

/// <summary>
/// The smallest create: one document, in four scenarios. The usual way first (the id declared in the schema, an ObjectId
/// ARX makes), then the id declared on the entity, then an id you supply, then a Guid id.
/// </summary>
/// <remarks>
/// The declared id is the document's <c>_id</c>. Your code names it by the column you declare (<c>account_id</c>); MongoDB
/// stores it as <c>_id</c>. A collection that doesn't exist yet is made by MongoDB on the first insert.
/// </remarks>
public sealed class Basic1_CreateOneRecord : ISample
{
    public string Name => "create-basics-1-create-one-record";

    public string Title => "Create one record and get its id";

    public async Task RunAsync(SampleContext dbContext)
    {
        await Scenario1_IdInTheSchemaAsync(dbContext.ConnectionString);

        await Scenario2_IdOnTheEntityAsync(dbContext.ConnectionString);

        await Scenario3_AnIdYouSupplyAsync(dbContext.ConnectionString);

        await Scenario4_AGuidIdAsync(dbContext.ConnectionString);
    }

    /// <summary>1. The usual way: the id declared in the schema; ARX makes an ObjectId and returns it as text.</summary>
    private static async Task Scenario1_IdInTheSchemaAsync(string connectionString)
    {
        Step("1. Id in the schema");

        // Declare each collection's id once, at startup. A generated string id is an ObjectId.
        var schema = ArxSchemaCatalog.Create()
            .Table("account", ArxIdColumn.Generated<string>("account_id"))
            .Build();

        var service = new ArxMongoDbService(connectionString, schema);

        var entity = new ArxEntity("account");
        entity["name"] = "Northwind Traders";
        entity["account_number"] = "ACC-M001";
        entity["employee_count"] = 240;

        // CreateAsync returns the id of the new document: the ObjectId's 24 hexadecimal characters.
        ArxRecordId id = await service.CreateAsync(entity);

        Show($"created account {id.AsString()}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.account.find({ account_number: "ACC-M001" })
         * -- Expect: 1 document, _id an ObjectId, name "Northwind Traders", employee_count 240.
         * ===========================================================
         */
    }

    /// <summary>2. The other way: no schema catalog, the id declared on the entity.</summary>
    private static async Task Scenario2_IdOnTheEntityAsync(string connectionString)
    {
        Step("2. Id on the entity");

        var service = new ArxMongoDbService(connectionString);

        var entity = new ArxEntity("account");
        entity.IdColumn = ArxIdColumn.Generated<string>("account_id");
        entity["name"] = "Contoso Pharmaceuticals";
        entity["account_number"] = "ACC-M002";

        await service.CreateAsync(entity);

        // The id is also set on the entity.
        Show($"created account {entity.RecordId} (read from entity.RecordId)");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.account.find({ account_number: "ACC-M002" })
         * -- Expect: 1 document, name "Contoso Pharmaceuticals".
         * ===========================================================
         */
    }

    /// <summary>3. An id you supply: a country's code is its id.</summary>
    private static async Task Scenario3_AnIdYouSupplyAsync(string connectionString)
    {
        Step("3. An id you supply");

        var schema = ArxSchemaCatalog.Create()
            .Table("country", ArxIdColumn.Supplied<string>("code"))
            .Build();

        var service = new ArxMongoDbService(connectionString, schema);

        var portugal = new ArxEntity("country");
        portugal["code"] = "PT";
        portugal["name"] = "Portugal";

        ArxRecordId id = await service.CreateAsync(portugal);

        Show($"created country {id.AsString()}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.country.find({ _id: "PT" })
         * -- Expect: 1 document, name "Portugal".
         * ===========================================================
         */
    }

    /// <summary>4. A Guid id ARX makes (version 7: new ids sort by time).</summary>
    private static async Task Scenario4_AGuidIdAsync(string connectionString)
    {
        Step("4. A Guid id");

        var schema = ArxSchemaCatalog.Create()
            .Table("sales_order", ArxIdColumn.Generated<Guid>("order_id"))
            .Build();

        var service = new ArxMongoDbService(connectionString, schema);

        var order = new ArxEntity("sales_order");
        order["order_number"] = "SO-M001";
        order["total"] = 125.50m;

        ArxRecordId id = await service.CreateAsync(order);

        Show($"created order {id.AsGuid()}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.sales_order.find({ order_number: "SO-M001" })
         * -- Expect: 1 document, _id a UUID, total NumberDecimal("125.50").
         * ===========================================================
         */
    }
}

  > 1. Id in the schema
      created account 6af53399305d3c89be8228e9
  > 2. Id on the entity
      created account 6af53399305d3c89be8228ea (read from entity.RecordId)
  > 3. An id you supply
      created country PT
  > 4. A Guid id
      created order 01a1cdd1-8e34-764a-b3f7-7ff0c343ec37