Firely .NET SDK

https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/
Admin
Firely .NET SDK is a support library for working with HL7 FHIR on the Microsoft .NET platform,...
Tokens:82,841
Snippets:600
Trust Score:9
Update:6 hours ago
Show doc for...
Tokens:
Raw
### Install Hl7.Fhir.R4 via .NET CLI

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/getting-started.html

Use this command to add the Hl7.Fhir.R4 NuGet package to your project. This is the recommended way to install the SDK for FHIR R4.

```bash
dotnet add package Hl7.Fhir.R4
```

--------------------------------

### CachedResolver with MultiResolver and DirectorySource

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/resource-resolving/standard-resolvers.html

Example demonstrating how to use a resolver to resolve a resource by canonical URI, combining several standard resolvers.

```APIDOC
## CachedResolver with MultiResolver and DirectorySource

### Description
This example shows how to instantiate a CachedResolver wrapping a MultiResolver that combines a DirectorySource, a ZipSource, and a WebResolver, and then use it to resolve a resource by its canonical URI.

### Method
TryResolveByCanonicalUriAsync

### Endpoint
N/A (SDK method)

### Parameters
#### Method Parameters
- **canonicalUri** (string) - Required - The canonical URI of the resource to resolve.

### Request Example
```csharp
var resolver = new CachedResolver(
    new MultiResolver(
        new DirectorySource("path/to/directory"),
        ZipSource.CreateValidationSource(),
        new WebResolver()));

var result = await resolver.TryResolveByCanonicalUriAsync("http://hl7.org/fhir/StructureDefinition/Patient");
```

### Response
#### Success Response
- **result** (object) - The resolved resource, or null if not found.

#### Response Example
```csharp
var result = await resolver.TryResolveByCanonicalUriAsync("http://hl7.org/fhir/StructureDefinition/Patient");
```
```

--------------------------------

### Example Observation resource in JSON

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/isourcenode.html

Shows the instance data for an example Observation resource, used to illustrate the ISourceNode tree structure. The JSON includes a code with a coding array and a valueQuantity with a value.

```json
{
    "resourceType": "Observation",
    "code":
    {
        "coding": [ { "code": "7113001", "system": "http://snomed.info/sct" }, { "et" : "cetera" } ]
    },
    "valueQuantity":
    {
        "value": "185"
    }
}
```

--------------------------------

### Complete example with extern alias and using aliases

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/model/multiple-fhir-versions.html

Combines extern alias declarations, using aliases, and a simple Program class to demonstrate creating Patient objects from both STU3 and R4 in the same file.

```csharp
extern alias r4;
extern alias stu3;

using System;
using Hl7.Fhir.Model;
using R4 = r4::Hl7.Fhir.Model;
using STU3 = stu3::Hl7.Fhir.Model;

namespace MultipleVersions
{
        class Program
        {
                static void Main(string[] args)
                {
                        Console.WriteLine("Hello World!");

                        var code = new Code();

                        var patient1 = new STU3.Patient();
                        var patient2 = new R4.Patient();

                }
        }
}
```

--------------------------------

### System-wide search for resources with name 'foo' using WholeSystemSearchAsync

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/client/search.html

Executes a search across all resource types using WholeSystemSearchAsync. The example searches for any resource with 'foo' in its name, returning both Patients and Devices.

```csharp
Bundle results = await client.WholeSystemSearchAsync(new string[] { "name=foo" });
```

--------------------------------

### Evaluate from Bundle root for resolve()

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/fhirpath/best-practices.html

Shows that evaluating from the Bundle root allows `resolve()` to find other entries, while starting from a nested Patient node does not.

```csharp
Bundle b = new() {...}

// The engine has worked from the root of the bundle down, so it knows how to resolve to other entries
var active = b.Select("Bundle.entry.ofType(Patient).organization.resolve()");

// The engine was started from the nested Patient node, so it does not know how to find other entries.
var patient = b.Entry.Select(e => e.Resource).OfType<Patient>().First();
var active2 = patient.Select("organization.resolve()");
```

--------------------------------

### Resolve a resource using CachedResolver and MultiResolver

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/resource-resolving/standard-resolvers.html

Shows how to combine DirectorySource, ZipSource.CreateValidationSource(), and WebResolver in a MultiResolver wrapped by CachedResolver, then resolve a resource by canonical URI. The example uses several resolvers documented on this page.

```csharp
var resolver = new CachedResolver(
    new MultiResolver(
        new DirectorySource("path/to/directory"),
        ZipSource.CreateValidationSource(),
        new WebResolver()));

var result = await resolver.TryResolveByCanonicalUriAsync("http://hl7.org/fhir/StructureDefinition/Patient");
```

--------------------------------

### Create FhirPackageSource from package server with names and versions

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/resource-resolving/fhirpackagesource.html

Creates a FhirPackageSource by specifying a FHIR package server and package names with versions using '@'. The packages are installed locally before creating the source. Requires an active internet connection unless packages are already cached.

```csharp
var package1 = "hl7.fhir.r3.core.xml@3.0.2";
var package2 = "hl7.fhir.r3.expansions@3.0.2";
FhirPackageSource resolver = new(ModelInfo.ModelInspector, "https://packages.simplifier.net", new string[] { package1, package2 });
```

--------------------------------

### Configure Validator with custom schema resolver and settings

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/validation/profile-validation-internals.html

Example of constructing a Validator with a custom schema resolver and ValidationSettings to treat best-practice constraints as errors. Uses a CachedResolver and LocalTerminologyService.

```csharp
// The same resource resolver and terminology service as on the profile-validation page.
var resourceResolver = new CachedResolver(
    FhirPackageSource.CreateCorePackageSource(ModelInfo.ModelInspector, FhirRelease.STU3, "https://packages.simplifier.net"));
var terminologyService = new LocalTerminologyService(resourceResolver);

// A schema resolver you construct yourself, so you control its caching and any custom ISchemaBuilders.
var schemaResolver = StructureDefinitionToElementSchemaResolver.CreatedCached(resourceResolver);
var settings = new ValidationSettings { ConstraintBestPractices = ValidateBestPracticesSeverity.Error };

var validator = new Validator(resourceResolver, terminologyService, settings: settings, schemaResolver: schemaResolver);

var patient = new Patient();
var outcome = validator.Validate(patient);
```

--------------------------------

### Using Catch() to handle parsing errors

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/errorhandling.html

Shows how to install an error callback using the Catch() extension method within a using block. The callback collects exceptions into a list while navigating the FHIR node. The handler is automatically uninstalled when leaving the block.

```csharp
List<Exception> allExceptions = new List<Exception>();
var src = FhirXmlNode.Parse("....");

using (src.Catch((_, arg) => allExceptions.Add(arg.Exception)))
{
    // navigate through src, or feed the instance to another
    // consumer, which will navigate it for you:
    var poco = src.ToPoco();
}
```

--------------------------------

### Set up a FHIR Patient resource with Firely .NET SDK

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/model/patient-example.html

This example creates a Patient instance and populates it with an identifier, official and nickname names, gender, birth date, birth place and birth time extensions, mother's maiden name extension, an address, a contact, and deceased status. It shows multiple ways to assign values, such as using WithGiven/AndFamily fluent methods, object initializers, and the SetString extension method.

```csharp
	// example Patient setup, fictional data only
	var pat = new Patient();

	var id = new Identifier();
	id.System = "http://hl7.org/fhir/sid/us-ssn";
	id.Value = "000-12-3456";
	pat.Identifier.Add(id);
	
	var name =  new HumanName().WithGiven("Christopher").WithGiven("C.H.").AndFamily("Parks");
	name.Prefix = new string[] { "Mr." };
	name.Use = HumanName.NameUse.Official;
	
	var nickname = new HumanName();
	nickname.Use = HumanName.NameUse.Nickname;
	nickname.GivenElement.Add(new FhirString("Chris"));
	
	pat.Name.Add(name);
	pat.Name.Add(nickname);
	
	pat.Gender = AdministrativeGender.Male;
	
	pat.BirthDate = "1983-04-23";
	
	var birthAddress = new Address() { City = "Seattle" };
	pat.AddExtension("http://hl7.org/fhir/StructureDefinition/birthPlace", birthAddress);

	pat.BirthDate = "1983-04-23";
	pat.BirthDateElement.AddExtension("http://hl7.org/fhir/StructureDefinition/patient-birthTime", 
  		new FhirDateTime(1983, 4, 23, 7, 44));
	pat.SetString("http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName", "Kramer");
	
	var address = new Address()
	{
		Line = new string[] { "3300 Washtenaw Avenue, Suite 227" },
		City = "Ann Arbor",
		State = "MI",
		PostalCode = "48104",
		Country = "USA"
	};
	pat.Address.Add(address);
	
	var contact = new Patient.ContactComponent();
	contact.Name = new HumanName();
	contact.Name.Given = new string[] { "Susan" };
	contact.Name.Family = "Parks";
	contact.Gender = AdministrativeGender.Female;
	contact.Relationship.Add(new CodeableConcept("http://hl7.org/fhir/v2/0131", "N"));
	contact.Telecom.Add(new ContactPoint(ContactPoint.ContactPointSystem.Phone, null, ""));
	pat.Contact.Add(contact);
	
	pat.Deceased = new FhirBoolean(false);
```

--------------------------------

### Construct in-memory tree with SourceNode

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/isourcenode.html

Builds an ISourceNode tree manually using the SourceNode class. The example creates a Patient node with contained resource and extensions. Using 'using static Hl7.Fhir.ElementModel.SourceNode;' can shorten the code.

```csharp
patient = SourceNode.Node("Patient", 
    SourceNode.Resource("contained", "Observation", SourceNode.Valued("valueBoolean", "true")),
    SourceNode.Valued("active", "true",
        annotatedNode,
        SourceNode.Valued("id", "myId2"),
        SourceNode.Node("extension",
            SourceNode.Valued("value", "4")),
        SourceNode.Node("extension",
            SourceNode.Valued("value", "world!"))));
```

--------------------------------

### TryDeserializeResource (non-throwing style)

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/error-handling.html

Example of using the non-throwing TryDeserializeResource method to get issues without exceptions.

```APIDOC
## TryDeserializeResource (non-throwing style)

### Description
Attempts to deserialize a FHIR resource from a reader, returning a bool and providing issues through an out parameter without throwing.

### Method
TryDeserializeResource

### Signature
`bool TryDeserializeResource(reader, out var patient, out var issues)`

### Parameters
- **reader** - Required - The reader containing the JSON data.
- **patient** (out) - Required - The deserialized resource if successful.
- **issues** (out) - Required - The list of issues (CodedException) encountered.

### Returns
- **bool** - True if deserialization succeeded, false otherwise.

### Example
```csharp
if (!deserializer.TryDeserializeResource(reader, out var patient, out var issues))
{
    foreach (var issue in issues)
        Console.WriteLine($"{issue.ErrorCode}: {issue.Message}");
}
```
```

--------------------------------

### Create a Bundle with manual entry and AddResourceEntry

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/model/bundles.html

Shows two ways to add resources to a Bundle: manually creating an EntryComponent with a FullUrl and resource, and using the AddResourceEntry method with a temporary UUID. The Bundle type is set to Collection, requiring all resources to have a FullUrl.

```csharp
var collection = new Bundle();
collection.Type = Bundle.BundleType.Collection;

// Adding the first entry manually
var first_entry = new Bundle.EntryComponent();
first_entry.FullUrl = $"{res1.ResourceBase}{res1.ResourceType}{res1.Id}";
first_entry.Resource = res1;
collection.Entry.Add(first_entry);

// Adding a second entry using AddResourceEntry
collection.AddResourceEntry(res2, "urn:uuid:01d04293-ed74-4f93-aa0a-2f096a693fb1");
```

--------------------------------

### Define and register custom ClassMappings with ModelInspector

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/model/custom-mappings.html

Creates a custom complex datatype 'MyMeasurement' and a custom resource 'MyObservation' using DynamicDataType and DynamicResource, registers them with a fresh ModelInspector, and round-trips an instance through JSON. The example starts from a fresh inspector populated with standard R4 types and uses CreateInstance() to set DynamicTypeName automatically.

```csharp
// Start from a fresh inspector populated with the standard R4 types.
var inspector = new ModelInspector(FhirRelease.R4);
inspector.Import(typeof(ModelInfo).Assembly);

// Look up primitive ClassMappings to use as property types.
var stringMapping = inspector.FindClassMapping("string")!;
var integerMapping = inspector.FindClassMapping("integer")!;

// Define a custom complex datatype 'MyMeasurement' with two elements.
var measurementMapping = new ClassMapping(inspector, "MyMeasurement", typeof(DynamicDataType), dt =>
[
    new PropertyMapping(dt, "unit", typeof(FhirString), [stringMapping]) { Order = 10 },
    new PropertyMapping(dt, "score", typeof(Integer), [integerMapping]) { Order = 20 }
])
{
    Canonical = "http://example.org/fhir/StructureDefinition/MyMeasurement"
};

// Define a custom resource 'MyObservation' with a choice element 'value'
// that can be either a string or a MyMeasurement.
var observationMapping = new ClassMapping(inspector, "MyObservation", typeof(DynamicResource), r =>
[
    new PropertyMapping(r, "subject", typeof(FhirString), [stringMapping]) { Order = 10 },
    new PropertyMapping(r, "value", typeof(DataType), [stringMapping, measurementMapping]) { Order = 20 }
])
{
    Canonical = "http://example.org/fhir/StructureDefinition/MyObservation"
};

// Register the custom mappings with the inspector.
inspector.ClassMappings.Add(measurementMapping);
inspector.ClassMappings.Add(observationMapping);

// CreateInstance() sets DynamicTypeName automatically from the mapping name.
var measurement = (DynamicDataType)measurementMapping.CreateInstance();
measurement.SetValue("unit", new FhirString("kg"));
measurement.SetValue("score", new Integer(75));

var observation = (DynamicResource)observationMapping.CreateInstance();
observation.SetValue("subject", new FhirString("patient-1"));
observation.SetValue("value", measurement);

// Serialize and deserialize using the custom inspector.
var json = new BaseFhirJsonSerializer(inspector).SerializeToString(observation);
var parsed = new BaseFhirJsonDeserializer(inspector).DeserializeResource(json);
```

--------------------------------

### Serialize ITypedElement to XML and POCO

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/itypedelement-serialization.html

Shows how to convert an ITypedElement to an XML string and to a POCO of type Patient. This example continues from the previous section's example, using patientNode.ToTypedElement(zipSource).

```csharp
ITypedElement patientRootElement = patientNode.ToTypedElement(zipSource);
string xml = patientRootElement.ToXml();
Patient p = patientRootElement.ToPoco<Patient>();
```

--------------------------------

### Enable pretty or compact output with .Pretty()

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/system-text-json.html

Add .Pretty() (or .Compact()) to the options for indented output.

```csharp
var options = new JsonSerializerOptions().ForFhir().Pretty();
```

--------------------------------

### Create and configure a Patient.ContactComponent

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/model/backbone-elements.html

Shows how to instantiate a Patient.ContactComponent, set its name family, and add it to the patient's contact list. The comment indicates additional configuration may be needed.

```csharp
var contact = new Patient.ContactComponent();
contact.Name = new HumanName();
contact.Name.Family = "Parks";
// Configure additional contact details

pat.Contact.Add(contact);
```

--------------------------------

### DeserializeResource (throwing style)

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/error-handling.html

Example of using the throwing DeserializeResource method and catching DeserializationFailedException.

```APIDOC
## DeserializeResource (throwing style)

### Description
Deserializes a FHIR resource from a JSON string, throwing a DeserializationFailedException if any issues are detected.

### Method
DeserializeResource

### Signature
`DeserializeResource(string json)`

### Parameters
- **json** (string) - Required - The JSON string representing the FHIR resource.

### Exceptions
- **DeserializationFailedException** - Thrown when there are any issues during deserialization. Contains `Exceptions` (list of CodedException) and `PartialResult` (best-effort POCO).

### Example
```csharp
var json = """{ "resourceType": "Patient", "id": "example-patient" }""";
var deserializer = FhirJsonDeserializer.DEFAULT;
try
{
    var patient = deserializer.DeserializeResource(json);
}
catch (DeserializationFailedException e)
{
    Console.WriteLine(e.Message);
}
```
```

--------------------------------

### Create FhirClient with FhirClientSettings

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/client/setup.html

Initializes a FhirClient with custom settings: Timeout=0, PreferredFormat=Json, VerifyFhirVersion=true, ReturnPreference=Minimal. The client is created with the server URL 'http://server.fire.ly'.

```csharp
    var settings = new FhirClientSettings
        {
            Timeout = 0,
            PreferredFormat = ResourceFormat.Json,
            VerifyFhirVersion = true,
            ReturnPreference = ReturnPreference.Minimal
        };

var client = new FhirClient("http://server.fire.ly", settings)
```

--------------------------------

### DeserializeResource with unknown type

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/deserialization.html

Use DeserializeResource when the resource type is not known up front. The example checks if the result is a Patient and prints its Active property.

```csharp
Resource resource = FhirJsonDeserializer.DEFAULT.DeserializeResource(json);
if (resource is Patient patient)
    Console.WriteLine(patient.Active);
```

--------------------------------

### Resolve resources by type and id, and files by name or path using FhirPackageSource

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/resource-resolving/fps-resolve-artifacts.html

Shows how to find a resource by its type and id using TryResolveByUriAsync, and load files by name or relative filepath using LoadArtifactByName and LoadArtifactByPath.

```csharp
FhirPackageSource resolver = new(ModelInfo.ModelInspector, new string[] { package1, package2 });

//find resource by id
var pat = (await resolver.TryResolveByUriAsync("StructureDefinition/Patient")).Value as StructureDefinition;

//find file by name
Stream file = resolver.LoadArtifactByName("StructureDefinition-Patient.xml");

//find file by path
Stream file2 = resolver.LoadArtifactByPath("package/StructureDefinition-Patient.xml");
```

--------------------------------

### Create a batch transaction Bundle with TransactionBuilder

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/model/bundles.html

Demonstrates using TransactionBuilder to create a batch transaction Bundle that atomically updates res1 and creates res2. Requires specifying the base address and Bundle type, then adding operations and calling ToBundle().

```csharp
var tb = new TransactionBuilder("http://example.org/fhir", Bundle.BundleType.Batch);

tb.Update(res1);
tb.Create(res2);

var transactionBundle = tb.ToBundle();
```

--------------------------------

### Property metadata attributes example

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/model/model-metadata.html

Shows a property with metadata attributes indicating it is a choice element (FhirElement with Choice=ChoiceType.DatatypeChoice), allowed types (FhirDateTime and Period), and other constraints.

```csharp
/// <summary>
/// Time of assessment
/// </summary>
[FhirElement("effective", InSummary=true, Order=150, Choice=ChoiceType.DatatypeChoice)]
[CLSCompliant(false)]
[AllowedTypes(typeof(Hl7.Fhir.Model.FhirDateTime),typeof(Hl7.Fhir.Model.Period))]
[DataMember]
public Hl7.Fhir.Model.DataType? Effective
{
```

--------------------------------

### LocalTerminologyService.ValueSetValidateCode

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/terminology/implementations.html

Validates that a coded value is in the set of codes allowed by a value set. The value set is found through the provided IAsyncResourceResolver, for example a FhirPackageSource containing all the artifacts from a package.

```APIDOC
## LocalTerminologyService.ValueSetValidateCode

### Description
Validates that a coded value is in the set of codes allowed by a value set. The value set is found through the provided IAsyncResourceResolver, for example a FhirPackageSource containing all the artifacts from a package.

### Method
ValueSetValidateCode

### Parameters
- **Parameters** (Parameters) - Required - The input parameters for the validation, built with `ValidateCodeParameters`.
- **id** (optional) - Optional identifier.
- **useGet** (optional) - Boolean flag to use GET instead of POST.

### Response
Returns the operation's output as a `Parameters` or a single `Resource`.

### Notes
- Requires an `IAsyncResourceResolver` to find the FHIR resources it needs.
- If the resolver also implements a conformance source (`IConformanceSource`, or `ICommonConformanceSource` on FHIR versions after STU3), `LocalTerminologyService` can validate against implicitly defined value sets.
```

--------------------------------

### Create Parameters resource using helper method AddReplacePatchOperation

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/client/crud.html

Uses the SDK helper method to create the same replace patch operation more concisely. This is an alternative to the manual approach.

```csharp
var patch = new Parameters();
patch.AddReplacePatchOperation("Patient.name[0].given[0]", new FhirString("John"));
```

--------------------------------

### Check validation result for specific issue

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/validation/profile-validation.html

Use this to verify that a validation result contains a specific issue code. The example checks for CONTENT_ELEMENT_CHOICE_INVALID_INSTANCE_TYPE and asserts that Success is false.

```csharp
var result = validator.Validate(p);
result.Issue.SelectMany(i => i.Details.Coding).Should().Contain(c => c.Code == Issue.CONTENT_ELEMENT_CHOICE_INVALID_INSTANCE_TYPE.Code.ToString());
result.Success.Should().BeFalse();
```

--------------------------------

### Create a FhirClient with a server URL

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/client/setup.html

Creates a new FhirClient instance by passing the FHIR server endpoint URL as a string. The constructor is overloaded to accept a URI, and a second parameter can control whether a conformance check is performed (default is false). The client is not thread-safe, so create one per thread if needed.

```csharp
var client = new FhirClient("http://server.fire.ly");
```

--------------------------------

### Validate with custom validator

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/validation/poco-validation-internals.html

Pass a custom `IPocoValidator` implementation to the `Validate()` extension method to apply custom validation logic. The `validator` parameter is named `MyValidator` in this example.

```csharp
var errors = patient.Validate(validator: new MyValidator());
```

--------------------------------

### Using TransactionBuilder to create and send a transaction bundle

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/client/transactions.html

Shows how to build a transaction bundle with TransactionBuilder, add a Create and a Delete interaction, and send it with TransactionAsync. The builder is initialized with the server base URL and BundleType.Transaction (or Batch).

```csharp
var pat = new Patient() { /* set up data */ };
var client = new FhirClient("http://server.fire.ly");
var builder = new TransactionBuilder("http://server.fire.ly", Bundle.BundleType.Transaction); // or Batch

// Add a new entry to the bundle including the patient resource that needs to be created.
builder.Create(pat);

// Add a new entry to the bundle with instructions that Patient with id "1337" needs to be deleted.
builder.Delete("Patient", "1337");

// returns the transaction bundle
var bundle = builder.ToBundle();

// Send the transaction to the server.
var response = await client.TransactionAsync(bundle);
```

--------------------------------

### ExternalTerminologyService

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/terminology/implementations.html

Implements all of ITerminologyService and uses a FhirClient to delegate every operation to an external terminology server. Each operation accepts a bool useGet parameter to use GET instead of POST.

```APIDOC
## ExternalTerminologyService

### Description
Implements all of `ITerminologyService` and uses a `FhirClient` to delegate every operation to an external terminology server.

### Usage
Each operation accepts a `bool useGet = false` parameter; set it to `true` to make the client use the `GET` REST operation instead of `POST`.

### Example
See [A basic example](https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/terminology/basic-usage.html) for an example that expands a value set through an external server.
```

--------------------------------

### Initialize Validator and validate an Organization resource

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/validation/profile-validation.html

Sets up a package resolver for core STU3 packages, a cached resource resolver, a local terminology service, and a Validator. Then validates a new Organization instance against the standard Organization profile. The validator caches internal representations, so reuse the same instance for multiple validations.

```csharp
var packageServer = "https://packages.simplifier.net";
var fhirRelease = FhirRelease.STU3;
var packageResolver = FhirPackageSource.CreateCorePackageSource(ModelInfo.ModelInspector, fhirRelease, packageServer);
var resourceResolver = new CachedResolver(packageResolver);
var terminologyService = new LocalTerminologyService(resourceResolver);

var validator = new Validator(resourceResolver, terminologyService);
var testOrganization = new Organization { };

var profile = Canonical.ForCoreType("Organization").ToString();
var result = validator.Validate(testOrganization, profile);
```

--------------------------------

### Expand a value set with ExternalTerminologyService

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/terminology/basic-usage.html

Uses ExternalTerminologyService with a FhirClient to send an expand operation to a FHIR endpoint. The example expands a SNOMED CT refset with a filter and paging, returning a ValueSet.

```csharp
var client = new FhirClient("https://someterminologyserver.org/fhir");
var service = new ExternalTerminologyService(client);

var parameters = new ExpandParameters()
    .WithValueSet(url: "http://snomed.info/sct?fhir_vs=refset/142321000036106")
    .WithFilter("met")
    .WithPaging(count: 10);

var expanded = await service.Expand(parameters) as ValueSet;
```

--------------------------------

### Execute FhirPath on POCO and ITypedElement using IsTrue

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/fhirpath/introduction.html

Shows how to use the IsTrue extension method on both a POCO and an ITypedElement to check if a FhirPath expression evaluates to true. The example uses 'Patient.name.exists()'.

```csharp
Patient p = new() {...}
var hasName = p.IsTrue("Patient.name.exists()");

ITypedElement ite = FhirXmlNode.Parse(...).ToTypedElement(...);
hasName = ite.IsTrue("Patient.name.exists()");
```

--------------------------------

### Use specific functions for certain resource types with FhirPackageSource

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/resource-resolving/fps-resolve-artifacts.html

Demonstrates FindCodeSystemByValueSet, FindConceptMaps with source and target URIs, and FindNamingSystemByUniqueId to find specific conformance resources.

```csharp
FhirPackageSource resolver = new(ModelInfo.ModelInspector, new string[] { package1, package2 });

//Find CodeSystems by ValueSets
var cs = (await resolver.FindCodeSystemByValueSet("http://hl7.org/fhir/ValueSet/address-type")) as CodeSystem;

//Find ConceptMaps by source and/or target (sourceUri or targetUri can be null)
IEnumerable<Resource> cms = await resolver.FindConceptMaps(sourceUri: "http://hl7.org/fhir/ValueSet/data-absent-reason", targetUri: "http://hl7.org/fhir/ValueSet/v3-NullFlavor");

//Find NamingSystem by uniqueId
var ns = (await resolver.FindNamingSystemByUniqueId("http://snomed.info/sct")) as NamingSystem;
```

--------------------------------

### Create Identifier with C# initializer syntax

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/model/datatypes.html

Shows how to instantiate a complex data type (Identifier) using C# object initializer syntax, setting System and Value properties.

```csharp
var id = new Identifier()
{
  System = "http://hl7.org/fhir/sid/us-ssn",
  Value = "000-12-3456"
};
```

--------------------------------

### Read a resource using ResourceIdentity.Build

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/client/crud.html

Uses the ResourceIdentity class to construct a resource URI from type and ID variables, since ReadAsync only takes URLs. This example reads a Patient with id '33'.

```csharp
var patResultC = await client.ReadAsync<Patient>(ResourceIdentity.Build("Patient","33"));
```

--------------------------------

### Routing with TerminologyServiceRoutingSettings

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/terminology/composing-services.html

Configures routing so that value sets matching preferred patterns are sent to specific services first. Uses wildcard '*' in patterns. Services are tried in constructor order for unmatched value sets.

```csharp
var local = new LocalTerminologyService(ZipSource.CreateValidationSource());
var localRouting = new TerminologyServiceRoutingSettings(local)
{
    PreferredValueSets = new string[]{"http://fire.ly/ValueSet/*"}
};

var client = new FhirClient("https://someterminologyserver.org/fhir");
var external = new ExternalTerminologyService(client);
var externalRouting = new TerminologyServiceRoutingSettings(external)
{
    PreferredValueSets = new string[]{"http://hl7.fhir.org/ValueSet/*"}
};

var multi = new MultiTerminologyService(localRouting, externalRouting);
```

--------------------------------

### Paging through results with ContinueAsync

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/client/paging.html

Loops through pages of a FHIR Bundle using ContinueAsync until null is returned, indicating no more pages. The second example shows how to jump directly to the last page using PageDirection.Last.

```csharp
while (result != null)
{
    // Do something with the entries in the result Bundle

    // retrieve the next page of results
    result = await client.ContinueAsync(result);
}

// go to the last page with the direction filled in:
var last_page = await client.ContinueAsync(result, PageDirection.Last);
```

--------------------------------

### Create and use a Recoverable serialization engine

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/serialization-engine.html

Creates a serialization engine using FhirSerializationEngineFactory.Recoverable with the model inspector, then deserializes a JSON string to a resource and serializes it back to XML. The engine works only with strings and resources.

```csharp
var engine = FhirSerializationEngineFactory.Recoverable(ModelInfo.ModelInspector);

Resource? patient = engine.DeserializeFromJson(json);
string xml = engine.SerializeToXml(patient);
```

--------------------------------

### WholeSystemSearchAsync(string[] criteria = null, string[] includes = null, int? pageSize = null)

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/client/search.html

Executes a search across all resource types on servers that support system-wide search. Returns a Bundle with matching resources of any type.

```APIDOC
## WholeSystemSearchAsync(string[] criteria = null, string[] includes = null, int? pageSize = null)

### Description
Executes a search across all resource types on servers that support system-wide search. Returns a Bundle with matching resources of any type.

### Method
WholeSystemSearchAsync

### Parameters
#### Parameters
- **criteria** (string[]) - Optional - Search criteria as they would appear on the search URL.
- **includes** (string[]) - Optional - Include directives for related resources.
- **pageSize** (int?) - Optional - Maximum number of results per page.

### Request Example
```csharp
Bundle results = await client.WholeSystemSearchAsync(new string[] { "name=foo" });
```

### Response
#### Success Response
Returns a Bundle containing resources of any type that match the criteria.

#### Response Example
```csharp
Bundle results = await client.WholeSystemSearchAsync(new string[] { "name=foo" });
```
```

--------------------------------

### Complete example: converting patientNode to ITypedElement

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/itypedelement.html

Demonstrates converting an ISourceNode (patientNode) into an ITypedElement using an external metadata provider (ZipSource.CreateValidationSource()). The resulting element's child 'active' is checked to have InstanceType 'boolean'.

```csharp
ISourceNode patientNode = ...
IResourceResolver zipSource = ZipSource.CreateValidationSource();
ITypedElement patientRootElement = patientNode.ToTypedElement(zipSource);
ITypedElement activeElement = patientRootElement.Children("active").First();
Assert.AreEqual("boolean", activeElement.InstanceType);
```

--------------------------------

### Parse XML string with FhirXmlNode.Parse

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/parsing/isourcenode.html

Parses an XML string into an ISourceNode and queries child elements. The example shows how to access the 'use' attribute value and its location. Swapping FhirXmlNode for FhirJsonNode allows parsing JSON with the same code.

```csharp
var xml = "<Patient xmlns=\"http://hl7.org/fhir\"><identifier>" +
    "<use value=\"official\" /></identifier></Patient>";
var patientNode = FhirXmlNode.Parse(xml);
var use = patientNode.Children("identifier").Children("use").First();
Assert.AreEqual("official", use.Text);
Assert.AreEqual("Patient.identifier[0].use[0]", use.Location);
```

--------------------------------

### Fluent Initializer for HumanName

Source: https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/model/other-features.html

Constructs a HumanName with given and family names using fluent methods WithGiven and AndFamily. Use this to build a name in a single statement; additional fields can be set later.

```csharp
pat.Name.Add(new HumanName().WithGiven("Christopher").WithGiven("C.H.").AndFamily("Parks"));
```
Tokens:
Raw