Elastic.CommonSchema 8.11.1

Elastic Common Schema .NET

Elastic.CommonSchema 项目包含 Elastic Common Schema (ECS) 的完整 C# 表示形式 - 请参阅 文档。

该库的目的是形成一个可靠且正确的基数，以便集成到使用Microsoft .NET和ECS的应用中。

这些类型可以直接使用，也可以与Elasticsearch的官方.NET客户端结合使用。这些类型使用了相应的DataMember属性进行注释，使得Elasticsearch.net客户端支持开箱即用的序列化。

另请参阅

• Elastic.Ingest.Elasticsearch.CommonSchema，以轻松将ECS文档持久化到Elasticsearch或Elastic Cloud。

包列表

.NET程序集以包名Elastic.CommonSchema发布到NuGet。

主分支在成功进行CI构建后将新的NuGet包推送到https://ci.appveyor.com/nuget/ecs-dotnet。

版本

Elastic.CommonSchema包的版本与发布的ECS版本相匹配，具有相同的对应分支名称。

• 嵌套架构（C#类型是从这个YAML文件生成的）：https://github.com/elastic/ecs/blob/v1.4.0/generated/ecs/ecs_nested.yml
• .NET类型：https://github.com/elastic/ecs-dotnet/tree/v1.4.0

NuGet包的版本号必须与Elasticsearch中使用的ECS精确版本相匹配。尝试使用不匹配的版本，例如，使用1.2.0版本的NuGet包而不是索引配置为使用1.1.0版本ECS模板的Elasticsearch索引，会导致索引和数据问题。

开始使用

安装

您可以通过包管理器控制台安装Elastic.CommonSchema。

PM> Install-Package Elastic.CommonSchema

或者，您可以在包管理器UI中简单地搜索Elastic.CommonSchema。

用法

创建ECS事件

创建新的ECS事件就像实例化一个对象一样简单。

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" } }
};

动态分配ECS字段

此外，还可以通过以下方式动态分配ecs字段：

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

这会将ecsDocument.Orchestrator.ClusterId分配给"id"，并在需要时自动创建一个新的Orchestrator实例。

不是已知ecs字段的任何string或boolean值都将分配给labels.*，其余的分配给metatetadata.*

关于Metadata属性的说明

C# EcsDocument类型包含一个名为Metadata的属性，其签名如下：

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

此属性不是ECS规范的一部分，但作为索引补充信息的手段而包含在内。

扩展EcsDocument

在实际使用中，如果使用IDictionary<string, object> Metadata属性不足以使用，或者有更清晰的ECS兼容文档结构的定义，可以创建EcsDocument对象的子类并提供自己的属性定义。

通过TryRead/ReceiveProperty/WriteAdditionalProperties，可以连接到EcsDocumentJsonConverter并读取/写入更多属性。

/// <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);
}

Elastic.CommonSchema.BenchmarkDotNetExporter项目采用这种方式，在域源目录中，BenchmarkDocument是EcsDocument的子类。

版权和许可

本软件版权（C）2014-2020归Elasticsearch BV所有。

这是免费软件，许可证为： Apache License Version 2.0。