Skip to content

Commit

Permalink
Rework docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@skwasjer
skwasjer committed May 10, 2019
1 parent 65dc0d8 commit b9b0487
Show file tree
Hide file tree
Showing 4 changed files with 158 additions and 152 deletions.
110 changes: 29 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,35 @@
[![Build status](https://ci.appveyor.com/api/projects/status/469oo89bngrkgh2l?svg=true)](https://ci.appveyor.com/project/skwasjer/ibannet)
[![NuGet](https://img.shields.io/nuget/v/IbanNet.svg)](https://www.nuget.org/packages/IbanNet/)
[![Tests](https://img.shields.io/appveyor/tests/skwasjer/IbanNet.svg)](https://ci.appveyor.com/project/skwasjer/ibannet/build/tests)

# IbanNet

IbanNet is a .NET library providing functionality to validate and parse an [International Bank Account Number](https://en.wikipedia.org/wiki/International_Bank_Account_Number) also known as IBAN.

## Usage
## Installation

#### Parse
The simplest way to use this library is to use the static `Parse` method:
Install IbanNet via the Nuget package manager or `dotnet` cli.

```csharp
Iban iban = Iban.Parse("NL91ABNA0417164300");
```powershell
Install-Package IbanNet
```

When parsing fails, an `IbanFormatException` is thrown, which contains a property Result which indicates the type of error that occurred.

#### TryParse

To parse an IBAN without throwing an exception use `TryParse`.

```csharp
Iban iban;
bool success = Iban.TryParse("NL91ABNA0417164300", out iban);
For Data Annotation integration:
```powershell
Install-Package IbanNet.DataAnnotations
```
For FluentValidation integration:
```powershell
Install-Package IbanNet.FluentValidation
```

The only downside is there is no way to retrieve the type of validation error that occurred if parsing fails.
---

#### IbanValidator
[![Build status](https://ci.appveyor.com/api/projects/status/469oo89bngrkgh2l?svg=true)](https://ci.appveyor.com/project/skwasjer/ibannet)
[![Tests](https://img.shields.io/appveyor/tests/skwasjer/IbanNet.svg)](https://ci.appveyor.com/project/skwasjer/ibannet/build/tests)

Lastly, you can use the validator directly. The benefit of using the validator is that it implements the `IIbanValidator` interface and can thus be mocked. Additionally, the `ValidationResult` provides extra context, like the matched country (if any).
| | | |
|---|---|---|
| `IbanNet` | [![NuGet](https://img.shields.io/nuget/v/IbanNet.svg)](https://www.nuget.org/packages/IbanNet/) [![NuGet](https://img.shields.io/nuget/dt/IbanNet.svg)](https://www.nuget.org/packages/IbanNet/) | [Documentation](src/IbanNet/README.md)
| `IbanNet.DataAnnotations` | [![NuGet](https://img.shields.io/nuget/v/IbanNet.DataAnnotations.svg)](https://www.nuget.org/packages/IbanNet.DataAnnotations/) [![NuGet](https://img.shields.io/nuget/dt/IbanNet.DataAnnotations.svg)](https://www.nuget.org/packages/IbanNet.DataAnnotations/) | [Documentation](src/IbanNet.DataAnnotations/README.md) |
| `IbanNet.FluentValidation` | [![NuGet](https://img.shields.io/nuget/v/IbanNet.FluentValidation.svg)](https://www.nuget.org/packages/IbanNet.FluentValidation/) [![NuGet](https://img.shields.io/nuget/dt/IbanNet.FluentValidation.svg)](https://www.nuget.org/packages/IbanNet.FluentValidation/) | [Documentation](src/IbanNet.FluentValidation/README.md) |

For example:
## Example with validator

```csharp
IIbanValidator validator = new IbanValidator();
Expand All @@ -45,70 +42,21 @@ if (validationResult.IsValid) {
}
```

### Iban type

`Iban.Parse` and `Iban.TryParse` return a type Iban. The Iban type is entirely optional, and if you use the validator directly you won't ever need to use this type.

However, this type does provide some useful features:
## Example with `Iban` type

#### Format IBAN
To convert an Iban type to a string, call the `ToString(string format)` method with either of 2 formats:

|Format|Result|
|---|---|
|"F" or `IbanNet.Iban.Formats.Flat`|NL91ABNA0417164300|
|"S" or `IbanNet.Iban.Formats.Partitioned`|NL91 ABNA 0417 1643 00|

If `ToString()` is called without format, defaults to 'F'.

#### Equals

Whether you parsed `NL91 ABNA 0417 1643 00` or `NL91ABNA0417164300`, these IBAN are considered equal.

#### Mocking the static Parse/TryParse methods

If you use the static methods because you would like to use the Iban type, you can still mock the underlying validator for testing purposes by setting the static property `Iban.Validator`.

## Installation

Install **IbanNet** via [NuGet](https://www.nuget.org/packages/IbanNet/).

### Visual Studio / .NET Framework
```powershell
Install-Package IbanNet
```

### .NET CLI
```
dotnet add package IbanNet
```csharp
Iban iban;
bool success = Iban.TryParse("NL91 ABNA 0417 1643 00", out iban);
```

### .NET target frameworks
- .NET Standard 2.0
- .NET Standard 1.6
- .NET Standard 1.2
- .NET 4.7
- .NET 4.5

### Build requirements
- Visual Studio 2017
- .NET Core 2.1 SDK
- .NET Core 2.0 SDK
- .NET Core 1.1 SDK
- .NET 4.7 targetting pack
- .NET 4.5 targetting pack

#### Contributions
### Contributions
PR's are welcome. Please rebase before submitting, provide test coverage, and ensure the AppVeyor build passes. I will not consider PR's otherwise.

#### Contributors
### Contributors
- skwas (author/maintainer)

## Useful info
### Useful info

- [Changelog](Changelog.md)
- [IbanNet supported regions](SupportedRegions.md)
- [Fiddle](https://dotnetfiddle.net/JeGa9x)
- Related/associated libraries
- [IbanNet.DataAnnotations](src/IbanNet.DataAnnotations/README.md)
- [IbanNet.FluentValidation](src/IbanNet.FluentValidation/README.md)
- [IbanNet supported regions](SupportedCountries.md)
- [Fiddle](https://dotnetfiddle.net/JeGa9x)
56 changes: 14 additions & 42 deletions src/IbanNet.DataAnnotations/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,18 @@
[![Build status](https://ci.appveyor.com/api/projects/status/469oo89bngrkgh2l?svg=true)](https://ci.appveyor.com/project/skwasjer/ibannet)
[![NuGet](https://img.shields.io/nuget/v/IbanNet.DataAnnotations.svg)](https://www.nuget.org/packages/IbanNet.DataAnnotations/)
[![Tests](https://img.shields.io/appveyor/tests/skwasjer/IbanNet.svg)](https://ci.appveyor.com/project/skwasjer/ibannet/build/tests)
# How to use IbanNet.DataAnnotations

# IbanNet.DataAnnotations
Data Annotations support to validate IBAN user input with [IbanNet](../IbanNet/README.md).

Data Annotations to validate IBAN user input.
[Package installation](../../README.md)

## Introduction

To validate user input in ASP.NET MVC and Web API, Microsoft provides .NET Data Annotations.
While there are other alternatives to validate user input, this library specifically provides Data Annotation support which allows **IbanNet** to easily integrate in existing MVC and Web API projects for both .NET Framework and .NET Core.

For more detailed info please visit:
- [Basic Introduction to Data Annotation in .Net Framework](https://code.msdn.microsoft.com/Basic-Introduction-to-Data-244734a4)
- [System.ComponentModel.DataAnnotations Namespace](https://msdn.microsoft.com/en-US/library/System.ComponentModel.DataAnnotations.aspx)

## Usage

#### By field or property ####
### By property ####

```csharp
public class InputModel
Expand Down Expand Up @@ -54,7 +49,7 @@ public class MyWebApiController : ApiController

```

#### By parameter ####
### By parameter ####

```csharp
public class MyController : Controller
Expand All @@ -75,10 +70,13 @@ public class MyController : Controller
You can use your favorite DI provider to provide an [`IIbanValidator`](../IbanNet/IIbanValidator.cs) to the validation attribute, as long as `IServiceProvider.GetService(Type)` is implemented.
If no instance of `IIbanValidator` is resolved from the DI container, the static `Iban.IbanValidator` property is used instead.

## FAQ
### Why would I need this package?
### .NET Core example ###

```csharp
services.AddSingleton<IIbanValidator, IbanValidator>();
```

While there are different alternatives to validate user input, a lot of projects rely on ASP.NET MVC and/or Web API which already use Data Annotations.
## FAQ

### How about directly using the Iban type?

Expand All @@ -93,7 +91,7 @@ public class InputModel
}
```

> See [IbanTypeConverter](../IbanNet/IbanTypeConverter.cs). The converter will be called during model binding allowing proper deserialization.
> See [IbanTypeConverter](../IbanNet/TypeConverters/IbanTypeConverter.cs). The converter will be called during model binding allowing proper deserialization.
However in this situation - when a validation error occurs - instead of gracefully populating the `ModelStateDictionary`, an exception is thrown during model binding. Whether or not that is acceptable depends on the project/team.

Expand All @@ -116,23 +114,7 @@ public class InputModel

Because validation has already occurred, the `Parse` method should always succeed.

## Installation

Install **IbanNet.DataAnnotations** via [NuGet](https://www.nuget.org/packages/IbanNet.DataAnnotations/).

#### Visual Studio / .NET Framework
```powershell
Install-Package IbanNet.DataAnnotations
```

#### .NET CLI
```
dotnet add package IbanNet.DataAnnotations
```

### Future enhancements
- Poll: add client side validation support via AJAX?
- Localization
## Requirements

### .NET target frameworks
- .NET Standard 2.0
Expand All @@ -147,14 +129,4 @@ dotnet add package IbanNet.DataAnnotations
- .NET Core 2.0 SDK
- .NET Core 1.1 SDK
- .NET 4.7 targetting pack
- .NET 4.5 targetting pack

#### Contributions
PR's are welcome. Please rebase before submitting, provide test coverage, and ensure the AppVeyor build passes. I will not consider PR's otherwise.

#### Contributors
- skwas (author/maintainer)

## Related libraries
- [IbanNet](../../README.md)
- [IbanNet.FluentValidation](../IbanNet.FluentValidation/README.md)
- .NET 4.5 targetting pack
34 changes: 5 additions & 29 deletions src/IbanNet.FluentValidation/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,9 @@
[![Build status](https://ci.appveyor.com/api/projects/status/469oo89bngrkgh2l?svg=true)](https://ci.appveyor.com/project/skwasjer/ibannet)
[![NuGet](https://img.shields.io/nuget/v/IbanNet.FluentValidation.svg)](https://www.nuget.org/packages/IbanNet.FluentValidation/)
[![Tests](https://img.shields.io/appveyor/tests/skwasjer/IbanNet.svg)](https://ci.appveyor.com/project/skwasjer/ibannet/build/tests)

# IbanNet.FluentValidation

[FluentValidation](https://fluentvalidation.net/) support to validate IBAN user input.

[Package installation](../../README.md)

## Introduction

This library provides a property validator for the [FluentValidation](https://fluentvalidation.net/) framework that can be used in your rules to verify IBAN user input.
Expand Down Expand Up @@ -51,21 +49,9 @@ services.AddTransient<IValidator<InputModel>, InputModelValidator>()
services.AddFluentValidation();
```

## Installation

Install **IbanNet.FluentValidation** via [NuGet](https://www.nuget.org/packages/IbanNet.FluentValidation/).
## Requirements

#### Visual Studio / .NET Framework
```powershell
Install-Package IbanNet.FluentValidation
```

#### .NET CLI
```
dotnet add package IbanNet.FluentValidation
```

#### Dependencies
### Dependencies

- FluentValidation 8.x

Expand All @@ -82,14 +68,4 @@ dotnet add package IbanNet.FluentValidation
- .NET Core 2.0 SDK
- .NET Core 1.1 SDK
- .NET 4.7 targetting pack
- .NET 4.5 targetting pack

#### Contributions
PR's are welcome. Please rebase before submitting, provide test coverage, and ensure the AppVeyor build passes. I will not consider PR's otherwise.

#### Contributors
- skwas (author/maintainer)

## Related libraries
- [IbanNet](../../README.md)
- [IbanNet.DataAnnotations](../IbanNet.DataAnnotations/README.md)
- .NET 4.5 targetting pack
Loading

0 comments on commit b9b0487

Please sign in to comment.