Elastic.CommonSchema 8.12.3

Prefix Reserved
dotnet add package Elastic.CommonSchema --version 8.12.3                
NuGet\Install-Package Elastic.CommonSchema -Version 8.12.3                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Elastic.CommonSchema" Version="8.12.3" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Elastic.CommonSchema --version 8.12.3                
#r "nuget: Elastic.CommonSchema, 8.12.3"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Elastic.CommonSchema as a Cake Addin
#addin nuget:?package=Elastic.CommonSchema&version=8.12.3

// Install Elastic.CommonSchema as a Cake Tool
#tool nuget:?package=Elastic.CommonSchema&version=8.12.3                

Elastic Common Schema .NET

The Elastic.CommonSchema project contains a full C# representation of Elastic Common Schema (ECS) - see documentation.

The intention is that this library forms a reliable and correct basis for integrations into Elasticsearch, that use both Microsoft .NET and ECS.

These types can be used in either as-is, or in conjunction with, the Official .NET clients for Elasticsearch. The types are annotated with the corresponding DataMember attributes, enabling out-of-the-box serialisation support with the Elasticsearch.net clients.

See also:

Packages

The .NET assemblies are published to NuGet under the package name Elastic.CommonSchema

The main branch pushes new NuGet packages on successful CI builds to https://ci.appveyor.com/nuget/ecs-dotnet

Versioning

The version of the Elastic.CommonSchema package matches the published ECS version, with the same corresponding branch names:

The version numbers of the NuGet package must match the exact version of ECS used within Elasticsearch. Attempting to use mismatched versions, for example a NuGet package with version 1.2.0 against an Elasticsearch index configured to use an ECS template with version 1.1.0, will result in indexing and data problems.

Getting started

Installing

You can install Elastic.CommonSchema from the package manager console:

PM> Install-Package Elastic.CommonSchema

Alternatively, simply search for Elastic.CommonSchema in the package manager UI.

Usage

Creating an ECS event

Creating a new ECS event is as simple as newing up an instance:

var ecsDocument = new EcsDocument
{
	Timestamp = DateTimeOffset.Parse("2019-10-23T19:44:38.485Z"),
	Dns = new Dns
	{
		Id = "23666",
		OpCode = "QUERY",
		Type = "answer",
		QuestionName = "www.example.com",
		QuestionType = "A",
		QuestionClass = "IN",
		QuestionRegisteredDomain = "example.com",
		HeaderFlags = new[] { "RD", "RA" },
		ResponseCode = "NOERROR",
		ResolvedIp = new[] { "10.0.190.47", "10.0.190.117" },
		Answers = new[]
		{
			new DnsAnswers
			{
				Data = "10.0.190.47",
				Name = "www.example.com",
				Type = "A",
				Class = "IN",
				Ttl = 59
			},
			new DnsAnswers
			{
				Data = "10.0.190.117",
				Name = "www.example.com",
				Type = "A",
				Class = "IN",
				Ttl = 59
			}
		}
	},
	Network = new Network
	{
		Type = "ipv4",
		Transport = "udp",
		Protocol = "dns",
		Direction = "outbound",
		CommunityId = "1:19beef+RWVW9+BEEF/Q45VFU+2Y=",
		Bytes = 126
	},
	Source = new Source { Ip = "192.168.86.26", Port = 5785, Bytes = 31 },
	Destination = new Destination { Ip = "8.8.4.4", Port = 53, Bytes = 95 },
	Client = new Client { Ip = "192.168.86.26", Port = 5785, Bytes = 31 },
	Server = new Server { Ip = "8.8.4.4", Port = 53, Bytes = 95 },
	Event = new Event
	{
		Duration = 122433000,
		Start = DateTimeOffset.Parse("2019-10-23T19:44:38.485Z"),
		End = DateTimeOffset.Parse("2019-10-23T19:44:38.607Z"),
		Kind = "event",
		Category = new[] { "network_traffic" }
	},
	Ecs = new Ecs { Version = "1.2.0" },
	Metadata = new Dictionary<string, object> { { "client", "ecs-dotnet" } }
};

Dynamically assign ECS fields

Additionally ecs fields can be dynamically assigned through

ecsDocument.AssignProperty("orchestrator.cluster.id", "id");

This will assign ecsDocument.Orchestrator.ClusterId to "id" and automatically create a new Orchestrator instance if needed.

Any string or boolean value that is not a known ecs field will be assigned to labels.* everything else to metatadata.*

A note on the Metadata property

The C# EcsDocument type includes a property called Metadata with the signature:

/// <summary>
/// Container for additional metadata against this event.
/// </summary>
[JsonPropertyName("metadata"), DataMember(Name = "metadata")]
public IDictionary<string, object> Metadata { get; set; }

This property is not part of the ECS specification, but is included as a means to index supplementary information.

Extending EcsDocument

In instances where using the IDictionary<string, object> Metadata property is not sufficient, or there is a clearer definition of the structure of the ECS-compatible document you would like to index, it is possible to subclass the EcsDocument object and provide your own property definitions.

Through TryRead/ReceiveProperty/WriteAdditionalProperties you can hook into the EcsDocumentJsonConverter and read/write additional properties.

/// <summary>
/// An extended ECS document with an additional property
/// </summary>
[JsonConverter(typeof(EcsDocumentJsonConverterFactory))]
public class MyEcsDocument : EcsDocument
{
	[JsonPropertyName("my_root_property"), DataMember(Name = "my_root_property")]
	public MyCustomType MyRootProperty { get; set; }

	protected override bool TryRead(string propertyName, out Type type)
	{
		type = propertyName switch
		{
			"my_root_property" => typeof(MyCustomType),
			_ => null
		};
		return type != null;
	}

	protected override bool ReceiveProperty(string propertyName, object value) =>
		propertyName switch
		{
			"my_root_property" => null != (MyRootProperty = value as MyCustomType),
			_ => false
		};

	protected override void WriteAdditionalProperties(Action<string, object> write) => write("my_root_property", MyCustomType);
}

The Elastic.CommonSchema.BenchmarkDotNetExporter project takes this approach, in the Domain source directory, where the BenchmarkDocument subclasses EcsDocument.

This software is Copyright (c) 2014-2020 by Elasticsearch BV.

This is free software, licensed under: The Apache License Version 2.0.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 is compatible.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (12)

Showing the top 5 NuGet packages that depend on Elastic.CommonSchema:

Package Downloads
Elastic.CommonSchema.Serilog

Serilog TextFormatter that formats log events in accordance with Elastic Common Schema (ECS).

Elastic.Ingest.Elasticsearch.CommonSchema

Package Description

Elastic.CommonSchema.NLog

NLog Layout that formats log events in accordance with Elastic Common Schema (ECS).

Elastic.Extensions.Logging

Elasticsearch logger provider for Microsoft.Extensions.Logging. Writes direct to Elasticsearch using the Elastic Common Schema (ECS), with semantic logging of structured data from message and scope values, for use with the Elasticsearch-Logstash-Kibana (ELK) stack. The results can be viewed and queried in the Kibana console.

Elasticsearch.Extensions.Logging

Elasticsearch logger provider for Microsoft.Extensions.Logging. Writes direct to Elasticsearch using the Elastic Common Schema (ECS), with semantic logging of structured data from message and scope values, for use with the Elasticsearch-Logstash-Kibana (ELK) stack. The results can be viewed and queried in the Kibana console.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
8.12.3 73,928 11/26/2024
8.12.2 192,847 10/22/2024
8.12.1 221,736 10/3/2024
8.12.0 40,887 9/26/2024
8.11.1 888,037 6/10/2024
8.11.0 615,271 4/10/2024
8.6.1 2,164,374 8/3/2023
8.6.0 472,794 5/9/2023
8.4.0-alpha4 36,680 3/28/2023
8.4.0-alpha3 14,642 3/15/2023
8.4.0-alpha2 2,104 3/1/2023
8.4.0-alpha1 2,387 2/20/2023
1.6.0-alpha1 278,768 6/2/2021
1.5.3 8,281,794 6/1/2021
1.5.1 1,606,316 6/3/2020
1.5.0 383,835 3/30/2020
1.4.4 3,570 3/25/2020
1.4.3 7,158 3/16/2020
1.4.2 26,353 3/6/2020
1.4.1 12,128 2/26/2020
1.4.0 17,243 1/29/2020
1.4.0-beta1 831 1/7/2020
1.2.0-alpha1 993 11/15/2019